Request payout

1. Get payment token

Start by generating a payment token. Make a HTTP POST request to the relevant endpoint + /api/oauth/token/ using the access token you generated.

Request

curl --location --request POST 'https://uat.app.payvyne.com/api/oauth/token' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id=<payment_key>'
--data-urlencode 'client_secret=<payment_secret>’

2. Create payout request

Then, create a PR. Send an HTTP POST request to the relevant endpoint + /api/v1/payouts including the headers Authorization: Bearer <payment_token>. The request body should contain an array of requests with customerReference, accountDetails, amount and currency corresponding to each payout required.

Request

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.

Response

{
    "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

{
    "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).


Did this page help you?