# Payment Request

Here we will teach you how to create and manage your payment requests. The payment request is the main element of our approval flow, which can be checked out by logging into our Web Banking.

The requests are bound to their respective cost centers and represent requests to execute specific payments, which can be transfers, boleto payments, etc. Expect more payment options to be introduced!

### The Payment Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the payment request. |
| `amount` | INTEGER | Amount in cents to be paid. |
| `centerId` | STRING | ID of the targeted cost center. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Description of the payment request. |
| `due` | STRING | Suggested payment date. Example: "2020-04-23". |
| `status` | STRING | Current payment request status. |
| `tags` | LIST OF STRINGS | Tags associated with the payment request. |
| `type` | STRING | Payment type. Options: "transfer", "brcode-payment", "boleto-payment", "utility-payment". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Payment Requests

`POST /v2/payment-request`

Use this route to create new payment requests in our Web Banking approval flow.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `centerId` | REQUIRED | Unique ID of the targeted cost center. You can check out the cost center ID directly on its approval section on our Web Banking. Example: 5656565656565656 |
| `payment` | REQUIRED | JSON specifying the requested payment. The payment JSON is the same as those passed in the requests that create the payments without going through the approval flow (see [transfer](https://docs.starkbank.com/api/v2/transfer.md) and [boleto payment](https://docs.starkbank.com/api/v2/boleto-payment.md)). The only exception is that the "scheduled" parameter cannot be sent on these JSONs, as the PaymentRequest "due" parameter already serves this purpose. The SDKs also accept their respective objects instead of JSONs. |
| `due` | OPTIONAL | Suggested payment date. This parameter may be altered by the controllers of the cost center. Default is today. Example: "2020-08-01" |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |
| `type` | CONDITIONALLY REQUIRED | Payment type. The SDKs will take care of this parameter for you if you use their specialized objects. But if you pass a dictionary in payment parameter you need to inform its type. Examples: "transfer", "brcode-payment", "boleto-payment", "utility-payment". |

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.Transfer(
            amount=100000000,
            bank_code="665",
            branch_code="2201",
            account_number="76543-8",
            tax_id="594.739.480-42",
            name="Daenerys Targaryen Stormborn",
        ),
        tags=["daenerys", "request/1234"]
    ),
])

for request in requests:
    print(request)
```

**Response**

```python
PaymentRequest(
    actions=[
        {
            'pictureUrl': '',
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296',
            'email': ''
        },
        {
            'pictureUrl': '',
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096',
            'email': 'rhaegar.targaryen@starkbank.com'
        }
    ],
    amount=100000000,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=Transfer(
        account_number=76543-8,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        name=Daenerys Targaryen Stormborn,
        tax_id=594.739.480-42
    ),
    status=pending,
    tags=['daenerys', 'request/1234'],
    type=transfer,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### List Payment Requests

`GET /v2/payment-request`

Here you can list and filter payment requests created by the requesting user. We return it paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `centerId` | REQUIRED | Unique ID of the targeted cost center. You can check out the cost center ID directly on its approval section on our Web Banking. Example: 5656565656565656 |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `sort` | OPTIONAL | Sort order considered in the response. Options are: "-created" and "-due". Default is "-created". |
| `status` | OPTIONAL | Filter payment requests by the specified status. Example: success |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `type` | OPTIONAL | Filters payment requests by the type inferred from the payment parameter, if it is not a dictionary. Example: boleto-payment |

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.query(center_id="4762954029334528", limit=1)

for request in requests:
    print(request)
```

**Response**

```python
PaymentRequest(
    actions=[
        {
            'pictureUrl': '',
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296',
            'email': ''
        },
        {
            'pictureUrl': '',
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096',
            'email': 'rhaegar.targaryen@starkbank.com'
        }
    ],
    amount=100000000,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=Transfer(
        account_number=76543-8,
        amount=100000000,
        bank_code=665,
        branch_code=2201,
        name=Daenerys Targaryen Stormborn,
        tax_id=594.739.480-42
    ),
    status=pending,
    tags=['daenerys', 'request/1234'],
    type=transfer,
    description=Daenerys Targaryen Stormborn (594.739.480-42),
    updated=2020-10-23T19:36:59.345760+00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/payment-request-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/payment-request-node.md)
- [PHP](https://docs.starkbank.com/api/v2/payment-request-php.md)
- [Java](https://docs.starkbank.com/api/v2/payment-request-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/payment-request-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/payment-request-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/payment-request-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/payment-request-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/payment-request-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/payment-request-curl.md)