# Payment Request

Payment Requests allow you to submit payment orders to be approved via the Web Banking approval flow. Each request is bound to a cost center, and controllers of that cost center can approve, deny, or schedule the payment.

You can request any type of payment supported by Stark Bank, including Transfers, Brcode Payments, Boleto Payments, Utility Payments, Tax Payments, and Darf Payments.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

TransferRequest a Pix or Ted transfer to another bank accountBrcode PaymentRequest a Pix QR code paymentBoleto PaymentRequest a boleto paymentUtility PaymentRequest a utility bill paymentTax PaymentRequest a tax payment with bar codeDarf PaymentRequest a federal tax payment without bar code (DARF)

## Setup

For each environment: (Sandbox or Production)

1. Create an account at Stark Bank.

2. Create a cost center with at least one controller in your Web Banking:

Settings > Cost Centers > New Cost Center

3. Create a webhook with the following subscription to receive events in your desired URL:

payment-request

3.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

3.2. Via API: 

Use the POST /webhook route to create the webhook

## Payment Request Overview

Payment Request is a resource that represents a request to execute a payment through the Web Banking approval flow. Each request is bound to a cost center, and controllers of that center can approve, deny, or schedule the payment.

The payment parameter accepts any of the following types: Transfer, BrcodePayment, BoletoPayment, UtilityPayment, TaxPayment, and DarfPayment.

To create a Payment Request, you need to provide the mandatory parameters: centerId and payment. Optional parameters include due and tags.

### The Payment Request Object

**Parameters**

| 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. |
| `description` | STRING | Description of the payment request. |
| `due` | STRING | Suggested payment date. Example: "2020-04-23". |
| `payment` | OBJECT | Payment object (Transfer, BrcodePayment, BoletoPayment, UtilityPayment, TaxPayment, or DarfPayment). |
| `type` | STRING | Payment type. Options: "transfer", "brcode-payment", "boleto-payment", "utility-payment", "tax-payment", "darf-payment". |
| `actions` | LIST OF OBJECTS | List of actions that have been taken on this payment request (approvals, denials, etc.). |
| `status` | STRING | Current payment request status. Options: "pending", "approved", "scheduled", "success", "canceled", "denied", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the payment request. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Payment Request Status

Each Payment Request has a status that can change over time according to its life cycle:

| Status | Description |
| --- | --- |
| Pending | The Payment Request was created and is waiting for approval. |
| Approved | The Payment Request was approved and the payment is being processed. |
| Scheduled | The Payment Request was approved and scheduled for the due date. |
| Success | The payment was successfully completed. |
| Canceled | The Payment Request was canceled before processing. |
| Denied | The Payment Request was denied by a cost center controller. |
| Failed | The payment execution failed. |

### Creating a Transfer Payment Request

To request a Transfer payment, pass a Transfer object as the payment parameter.

The Transfer object follows the same structure as a regular Transfer creation. The only exception is that the "scheduled" parameter should not be sent, as the PaymentRequest "due" parameter serves this purpose.

**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=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    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
)
```

### Creating a Brcode Payment Request

To request a Brcode (Pix QR code) payment, pass a BrcodePayment object as the payment parameter.

The BrcodePayment object follows the same structure as a regular Brcode Payment creation.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.BrcodePayment(
            brcode="00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF",
            tax_id="012.345.678-90",
            description="this will be fast",
        ),
        tags=["brcode", "request/5678"]
    ),
])

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    amount=123456,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=BrcodePayment(
        brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec52585,
        tax_id=012.345.678-90,
        description=this will be fast
    ),
    status=pending,
    tags=['brcode', 'request/5678'],
    type=brcode-payment,
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### Creating a Boleto Payment Request

To request a Boleto payment, pass a BoletoPayment object as the payment parameter.

The BoletoPayment object follows the same structure as a regular Boleto Payment creation.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.BoletoPayment(
            line="34191.09107 05447.947309 71544.640008 8 84660000011631",
            tax_id="38.435.677/0001-25",
            description="Payment for killing white walkers",
        ),
        tags=["boleto", "request/9012"]
    ),
])

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    amount=11631,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=BoletoPayment(
        line=34191.09107 05447.947309 71544.640008 8 84660000011631,
        tax_id=38.435.677/0001-25,
        description=Payment for killing white walkers
    ),
    status=pending,
    tags=['boleto', 'request/9012'],
    type=boleto-payment,
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### Creating a Utility Payment Request

To request a Utility payment, pass a UtilityPayment object as the payment parameter.

The UtilityPayment object follows the same structure as a regular Utility Payment creation.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.UtilityPayment(
            line="83640000001 1 08740138007 0 61053026111 0 08067159411 9",
            description="Electricity for the Long Night",
        ),
        tags=["utility", "request/3456"]
    ),
])

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    amount=100,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=UtilityPayment(
        line=83640000001 1 08740138007 0 61053026111 0 08067159411 9,
        description=Electricity for the Long Night
    ),
    status=pending,
    tags=['utility', 'request/3456'],
    type=utility-payment,
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### Creating a Tax Payment Request

To request a Tax payment, pass a TaxPayment object as the payment parameter.

The TaxPayment object follows the same structure as a regular Tax Payment creation.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.TaxPayment(
            bar_code="81660000005003657010074119002551100010601813",
            description="fix the road",
        ),
        tags=["tax", "request/7890"]
    ),
])

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    amount=500365,
    center_id=4762954029334528,
    created=2020-10-23T19:36:59.345753,
    due=2020-10-24T03:00:00+00:00,
    id=5756591424929792,
    payment=TaxPayment(
        bar_code=81660000005003657010074119002551100010601813,
        description=fix the road
    ),
    status=pending,
    tags=['tax', 'request/7890'],
    type=tax-payment,
    updated=2020-10-23T19:36:59.345760+00:00
)
```

### Creating a Darf Payment Request

To request a Darf (federal tax) payment, pass a DarfPayment object as the payment parameter.

The DarfPayment object follows the same structure as a regular Darf Payment creation.

**Request**

```python
import starkbank

requests = starkbank.paymentrequest.create([
    starkbank.PaymentRequest(
        center_id="4762954029334528",
        payment=starkbank.DarfPayment(
            revenue_code="1240",
            tax_id="012.345.678-90",
            competence="2023-09-01",
            nominal_amount=1234,
            fine_amount=12,
            interest_amount=34,
            due="2023-10-01",
            description="DARF Payment for revenue code 1240",
        ),
        tags=["darf", "request/4321"]
    ),
])

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    amount=1280,
    center_id=4762954029334528,
    created=2023-10-01T19:36:59.345753,
    due=2023-10-01T03:00:00+00:00,
    id=5756591424929792,
    payment=DarfPayment(
        revenue_code=1240,
        tax_id=012.345.678-90,
        competence=2023-09-01,
        nominal_amount=1234,
        fine_amount=12,
        interest_amount=34,
        due=2023-10-01,
        description=DARF Payment for revenue code 1240
    ),
    status=pending,
    tags=['darf', 'request/4321'],
    type=darf-payment,
    updated=2023-10-01T19:36:59.345760+00:00
)
```

### Listing Payment Requests

Get a list of Payment Requests using filters such as after, before, status and tags to narrow the results.

The centerId parameter is required for listing.

**Request**

```python
import starkbank

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

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

**Response**

```python
PaymentRequest(
    actions=[
        {
            'name': 'SDK Python',
            'action': 'requested',
            'type': 'project',
            'id': '5414728075575296'
        },
        {
            'name': 'Rhaegar Targaryen',
            'action': 'required',
            'type': 'member',
            'id': '6025356662276096'
        }
    ],
    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
)
```

---

## Other Languages

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