# Payouts

The Payout Service enables secure, automated disbursements such as supplier invoices, payroll and refunds, while eliminating transaction limits and the need for manual banking procedures. Funds are first placed in our dedicated client funds account before final disbursement via the national clearing system Bankgirot or Plusgirot. This guide shows you how to initiate a payout, as well as how to look up the creditor name to validate the Bankgiro or Plusgiro number of the recipient. 

> Requests to the Payout Service API require an [access token](get_access_token.md) with `scope` set to `paymentinitiation` `corporate`. 

##

### 1. Create Payout 

The first step of the payout process is to create a payout resource. This specifies the payout instructions to Open Payments for the final disbursement of funds. 

#### Endpoint

```http
POST /premium/v1/payouts
```

#### Headers

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

#### Request Body

| Name                     | Type         | Description                                                                                |
| ------------------------ | ------------ | ------------------------------------------------------------------------------------------ |
| `instructedAmount`       | object       | The amount and currency of the money to be transferred.                                    |
| `debtorAccount`          | object       | The account from which the payment will be debited.                                        |
| `creditorGiro`           | object       | The Bankgirot or Plusgirot account to which the payment will be credited.                  |
| `creditorName`           | string       | The full name of the payment recipient.                                                    |
| `creditorAgent`          | string       | The BIC of the payment recipient's bank.                                                   |
| `requestedExecutionDate` | string(date) | The date when the payment is scheduled to be executed in ISO 8601 format, e.g. 2025-10-31. |
| `invoiceRef`             | string       | A custom invoice reference.                                                                |
| `ocrRef`                 | string       | A Giro OCR reference.                                                                      |
| `debtorAccountMessage`   | string       | A personal message from the payer to themselves.                                           |
| `creditorAccountMessage` | string       | A personal message from the payer to the recipient.                                        |

```bash
curl -X POST "https://api.openbankingplatform.com/premium/v1/payouts" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: dda491aa-7434-4502-8861-7256f986cdbf" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -d '{
        "instructedAmount": {
          "currency": "SEK", 
          "amount": "1300.00"
        },
        "debtorAccount": {
          "iban": "SE123456789000532811",
          "currency": SEK"
        }, 
        "creditorGiro": {
          "giroNumber": "1234-5678",
          "giroType": "BANKGIRO"
        },
        "creditorName": "Acme AB",
        "creditorAgent": "HANDSESS",
        "requestedExecutionDate": "2026-01-01",
        "ocrRef": "1234567890",
        "debtorAccountMessage": "Personal note"
      }'
```

#### Response 

```json
{
  "payoutId": "a74fbba9-88d7-4dac-93a4-15d454cdafff",
  "transactionStatus": "RCVD",
  "_links": {
    "confirmPayout": {
      "href": "/premium/v1/payouts/confirm"
    },
    "self": {
      "href": "/premium/v1/payouts/a74fbba9-88d7-4dac-93a4-15d454cdafff"
    }
  }
}
```

### 2. Confirm Payout 

Then, you make the following request to confirm that there is an upcoming payout. 

#### Endpoint

```http
PUT /premium/v1/payouts/confirm
```

#### Headers

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

#### Request Body 

| Name        | Type  | Description                                            |
| ----------- | ----- | ------------------------------------------------------ |
| `payoutIds` | array | The IDs of the payouts to include in the confirmation. |

```bash
curl -X PUT "https://api.openbankingplatform.com/premium/v1/payouts/confirm" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 1397b1c9-62af-41d5-b201-cb6ef2f70a72" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -d '{
        "payoutIds": [
          "a74fbba9-88d7-4dac-93a4-15d454cdafff",
          "084702f9-805f-48dd-9e06-3d2e95309565",
          "1f728e86-650e-4529-a6e1-80f9b468ac61"
        ]
      }'
  ```

#### Response 

```json
{
  "reference": "OPENXU3WCG",
  "totalAmount": {
    "currency": "SEK",
    "amount": "1300.00"
  }
}
```
The response contains a generated payout `reference`, which will be used in the next step.

### 3. Send Funds 

After successfully confirming the payout, the funds should be sent to Open Payments' client funds account with the `reference` provided in the Confirm Payout response. This payment may be made via the [PIS](quickstart_pis.md) or any other payment method as long as it is referred to via said reference. Once we detect that the funds have been made available in our client funds account, they will automatically be disbursed to the ultimate beneficiary according to Bankgirot and Plusgirot's cut-off times. 

The general cut-off time for same-day settlement is 09:15 CET. For bank-specific cut-off times, please [contact us](mailto:support@openpayments.io).

### 4. Get Payout 

Finally, you can make the following request to check the status of the payout.

#### Endpoint 

```http
GET /premium/v1/payouts/{payoutId}
```

#### Path Parameters

| Name       | Type   | Description                            |
| ---------- | ------ | -------------------------------------- |
| `payoutId` | string | The ID of the payout that was created. |

#### Headers

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

```bash
curl -X GET "https://api.openbankingplatform.com/premium/v1/payouts/a74fbba9-88d7-4dac-93a4-15d454cdafff" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-Request-ID: 9c62543c-c8d8-43d8-a7a2-aef97c71fe17" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680"
```

#### Response

```json
{
  "creditorAgent": "HANDSESS",
  "remittanceInformationUnstructured": "1234567890",
  "debtorAccountMessage": "Personal note",
  "transactionStatus": "ACTC",
  "creditorAccount": {
    "bankgiroNumber": "1234-5678"
  },
  "creditorName": "Acme AB",
  "debtorAccount": {
    "iban": "SE123456789000532811",
    "currency": "SEK"
  },
  "instructedAmount": {
    "currency": "SEK",
    "amount": "1300.00"
  }
}
```
Once the funds have been settled in the beneficiary's account, the payout will have `transactionStatus` `ACTC`.