Make a payout

Get started

Making a payout as a Partner account follows the same approach as requesting a payout as a Merchant account, but uses separate endpoints and additional parameters. Start by familiarising yourself with payouts, including how to request and get status updates for payouts.

Once you're familiar with the process, you can recreate the steps with some minor differences.

📘

Helpful to know

You'll need to generate a partner access token. Learn how to do this in the Partner portal here.

Partner payout requests

Create a PR. Send an HTTP POST request to the relevant endpoint + /api/v1/partners/payouts/ including the header Authorization: Bearer <payment_token>.

In addition to the standard PR parameters, you must include an additional parameter merchantId.

Request

cURL

curl --location --request POST 'https://uat.app.payvyne.com/api/v1/partners/payouts' \
--header 'Authorization: Bearer <payment_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "a0adb8ed7178d2",
    "requests": [
        {
            "customerReference": "customer1",
            "accountDetails": {
              "accountNo": "63849203",
              "sortCode": "001111",
              "accountType": "SCAN"
            "amount": 2.4,
            "currency":"GBP",
            "idempotencyId": "2d83d3fe3-0848-4562-a263-96d7d761cf3r"
        },
        {
            "customerReference": "customer2",
            "accountDetails": {
              "accountNo": "63849203",
              "sortCode": "001111",
              "accountType": "SCAN"
            "amount": 9,
            "currency":"GBP",
            "idempotencyId": "22d83d3fe3-0848-4562-a263-96d7d761cf3r"
        },
        {
            "customerReference": "customer3",
            "accountDetails": {
              "accountNo": "63849203",
              "sortCode": "001111",
              "accountType": "SCAN"
            "amount": 0.1,
            "currency":"GBP",
            "idempotencyId": "2d83d3fe3-0848-4562-a263-96d7d761cf3r"
                    },
        {
            "customerReference": "customer4",
            "accountDetails": {
              "accountNo": "63849203",
              "sortCode": "001111",
              "accountType": "SCAN"
            "amount": 1,
            "currency":"GBP",
            "idempotencyId": "2d83d3fe3-0848-4562-a263-96d7d761cf3r"
        },
        {
            "customerReference": "customer5",
            "accountDetails": {
              "iban": "LT34 7750 5484 9468 1243",
              "accountType": "IBAN"
            "amount": 99999.99,
            "currency":"EUR",
            "idempotencyId": "2d83d3fe3-0848-4562-a263-96d7d761cf3r"
        },
        {
            "customerReference": "customer6",
            "accountDetails": {
              "iban": "LT34 3250 0909 3475 7655",
              "accountType": "IBAN"
            "amount": 1,
            "currency":"EUR",
            "idempotencyId": "2d83d3fe3-0848-4562-a263-96d7d761cf3r"
        }
    ]
}'

Parameter	Description
merchantId	16 digit alphanumeric merchant identifier - used to signify the Merchant account you wish to request payout for.

Response

JSON

{
    "payouts": [
        {
            "id": "94c7c2d41aa230a8",
            "status": "NEW",
            "amount": 2.4,
            "merchant": "a0adb8ed7178d2",
        },
        {
            "id": "4cb5427e221b9b5f",
            "status": "NEW",
            "amount": 9,
            "currency": "GBP",
            "merchant": "a0adb8ed7178d2",
        },
        {
            "id": "0411a04360207173",
            "status": "NEW",
            "amount": 1.00,
            "currency": "EUR",
            "merchant": "a0adb8ed7178d2",
        }
    ],
    "errors": [
        {
            "idempotencyId": "490da931-ea00-4aff-bffb-eed38cb4d00c",
            "errorMessage": "Could not find payment with reference=customerxxxxx"
        },
        {
            "idempotencyId": "nfkdnd845n5ke9jd9jt3",
            "errorMessage": "Payout exists with this idempotencyId!"
        }
    ]
}

Using partner webhook notifications

The payout status webhook includes an additional merchant parameter in the body to identify the Merchant account the payout relates to.

Response

JSON

{
  "type": "PAYOUT_STATUS_CHANGE",
  "merchant": "1f7rhste5rj0unf6",
  "payoutId": "4c0baba6eb85b05c",
  "status": "FAILED",
  "timestamp": 1632739441182,
  "amount": 10,
  "currency": "GBP"
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier of the Merchant account the payout was requested for.

📘

Helpful to know

We recommend checking account balance before creating a PR. Learn how to check account balance here.

👍

Try it out

Make sure you setup a callback URL in your Partner account to receive webhook notifications for payouts made from your account for any linked Merchant accounts.

Using partner payout status calls

You can request a payout status update on any payout at any time by sending an HTTP GET request to the relevant base URL + /api/v1/partners/payouts/ including the headers Authorization: Bearer <payment_token>.

Responses will include an additional merchant parameter in the body to identify the Merchant account the payout relates to.

Request

cURL

curl --location --request GET 'https://uat.app.payvyne.com/api/v1/partners/payouts/<payoutId>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <payment_token>'

Response

JSON

{
  "payoutId": "4c0baba6eb85b05c",
  "merchant": "1f7rhste5rj0unf6", 
  "status": "FAILED",
  "paymentId": "f4fce78db4020045",
  "amount": 10,
  "currency": "GBP"
}

Parameter	Description
merchant	16 digit alphanumeric merchant identifier of the Merchant account the payout was requested for.