Request payout

1. Create payout request

Create a PR. Send an HTTP POST request to the relevant endpoint + /api/v1/payouts including the headers Authorization: Bearer <payment_token>. You can use the same payment token generated previously.

The request body should contain an array of requests with customerReference, accountDetails, amount and currency corresponding to each payout required.

Request

cURL

curl --location --request POST 'https://uat.app.payvyne.com/api/v1/payouts' \
--header 'Authorization: Bearer <payment_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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": "2d83d3fe3-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"
    }
  ]
}'

requests

Parameter	Description
customerReference	128 characters alphanumeric reference field for customer ID.
accountDetails	Object containing the payee's account details.
amount	The amount of the payout.
currency	The three-character payout currency using ISO 4217. Vyne supports GBP and EUR.
idempotencyId	A unique value, between 16 and 64 characters, which the resource server uses to recognise subsequent retries of the same request.

accountDetails

Parameter	Description
accountNo	Payee's account number (GBP payments only)
sortCode	Payee's sort code (GBP payments only)
iban	Payee's IBAN (EUR payments only)
accountType	The type of account details. Available values are SCAN (GBP payments) and IBAN (EUR payments).

A successful PR returns a 202 response code and an object with payouts and/or errors arrays.

If something unexpected happened during the request, the API returns an error response with the appropriate HTTP status code and a JSON response that contains detailed information about the problem.

📘

Helpful to know

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

👍

Try it out

Unsuccessful payouts may be automatically reattempted before a failed status update is provided. Our API supports idempotency for safely retrying requests without accidentally performing the same operation twice. Read more about idempotent requests here.

Requests relating to separate payouts should use a unique idempotencyId if the previous request with the same idempotencyId was successful. If you send the same idempotencyId, the response will contain details of the original request and a new request won't be created. A webhook notification is sent containing the final payout status. If a payout status is FAILED, make the request again with a new idempotencyId to retry the payout safely.

Response

JSON

{
    "payouts": [{
            "id": "94c7c2d41aa230a8",
            "status": "NEW",
            "amount": 2.4,
            "customerReference": "customer1",
            "accountDetails": {
                "accountNo": "63849203",
                "sortCode": "001111",
                "accountType": "SCAN"
            }
        },
        {
            "id": "4cb5427e221b9b5f",
            "status": "NEW",
            "amount": 9,
            "currency": "GBP",
            "customerReference": "customer2",
            "accountDetails": {
                "accountNo": "63849203",
                "sortCode": "001111",
                "accountType": "SCAN"
            }
        },
        {
            "id": "0411a04360207173",
            "status": "NEW",
            "amount": 1.00,
            "currency": "EUR",
            "customerReference": "customer6",
            "accountDetails": {
                "iban": "LT34 3250 0909 3475 7655",
                "accountType": "IBAN"
            }
        }
    ],
    "errors": [
        {
            "idempotencyId": "490da931-ea00-4aff-bffb-eed38cb4d00c",
            "errorMessage": "Could not find payment with reference=customerxxxxx"
        },
        {
            "idempotencyId": "nfkdnd845n5ke9jd9jt3",
            "errorMessage": "Payout exists with this idempotencyId!"
        }
    ]
}

Additional error

JSON

{
    "timestamp": "2022-08-10T14:42:36.652+0000",
    "status": 400,
    "error": "Bad Request",
    "message": "Validation error",
    "details": {
        "method": "POST",
        "path": "/api/v1/payouts",
        "validationErrors": [
            {
                "errorCode": "INVALID_FIELD",
                "errorMessage": "Field=requests[0].idempotencyId The payout idempotency id size must be no more than 64! and more than 16"
            }
        ]
    }
}

Parameter	Description
payouts	Array of objects containing payouts that were initiated successfully.
errors	Array of objects containing error details for payouts that could not be initiated.

payouts

Parameter	Description
id	16 digit alphanumeric unique payout identifier.
status	The current status of the payout. For all possible statuses see here.
amount	The amount of the payout.
currency	The three-character payout currency using ISO 4217.
customerReference	128 characters alphanumeric reference field for customer ID.
accountDetails	Object containing the payee's account details.

errors

Parameter	Description
customerReference	128 characters alphanumeric reference field for customer ID.
accountDetails	Object containing the payee's account details.
errorMessage	A short description explaining why the payout initiation failed.

accountDetails

Parameter	Description
accountNo	Payee's account number (GBP payments only)
sortCode	Payee's sort code (GBP payments only)
iban	Payee's IBAN (EUR payments only)
accountType	The type of account details. Available values are SCAN (GBP payments) and IBAN (EUR payments).