Direct payouts allow merchants to choose which customer bank accounts are used. This instruction is used for Options 4-6 from Instant Payouts.

To make an Direct Payout, the merchant will make a call to instruct a payout to a specific bank account using either the customerBankAccountId Obtaining the account or by sending the bank account details in the request.

Direct Payout Instruction

The following call is an HTTPS POST request

Production - https://api.yaspa.com/v2/payouts/verified/transaction/initiate
Test Sandbox - https://testapi.yaspa.com/v2/payouts/verified/transaction/initiate

Headers

The following header must be attached to the request.

For security reasons, a Signature and Expires-at header needs to be attached. See Instant Payouts - Signing Payout Instructions for more details.

Header	Description
AuthorizationCitizen	This is the merchant api key from the Admin Dashboard - found on the Company Settings page. This secures the request to the merchant account
Expires-at	UNIX timestamp for signature expiration
Signature	Base 64 encoded signature
Content-Type	'application/json'

Body - Mandatory Fields

The body of the request is a JSON object; the following keys/values are mandatory on the request

key	Description	Values	Example
customerIdentifier	The merchant string reference for the customer. This must be unique per the customer. Yaspa uses the customerIdentifier to create saved accounts, so it's important no two customers share the same customerIdentifier.	String	"5f767df845"
currency	A 3-letter ISO-4217 Currency code. Currently, only EUR and GBP are supported	String	"EUR" or "GBP"
amount	The currency in decimal format. A value of 1.50 represents £1.50 in GBP currency	String	"1.50"
paymentGiro	The payment rail to be used for the payment. This must match the currency For GBP use FPS For EUR use SEPA (We will use either SCT or Sepa Instant based on the customer bank)	String	"FPS" or "SEPA"
reference	A unique reference for the payment, this will be used in payment reconciliation. This must be unique for the merchant account and less than 17 characters, this is a limitation passed on from the bank	String	"gjkhg43hjkfds43"
isQueued	Merchants who wish to approve payouts before they are submitted to their bank need to set this to true.	boolean	true or false
customerBankAccount	Receiving bank account details. This can be either a Customer Account ID from a previous pay-in or account verification, UK bank account details, or SEPA bank account details.	Object	See examples below

Body - Example bodies

Below is an example body of a payout instruction.

Please change the reference each time a payout instruction is used.

Request body with Customer Account ID

{   "customerIdentifier": "1234567",
    "paymentGiro": "FPS", 
    "amount": "0.01",
    "currency": "GBP",
    "reference": "{{randomString}}",
    "customerBankAccount": {
        "type": "CustomerAccountId",
        "value": "86f5d000-26bc-4bb1-8762-2b51d34f0c0e"
    }
}

Request body with UK account number and sort code

{   "customerIdentifier": "1234567",
    "paymentGiro": "FPS", 
    "amount": "0.01",
    "currency": "GBP",
    "reference": "{{randomString}}",
    "customerBankAccount":{
        "type":"AccountNumberAndSortCode",
        "bankAccountHolderName":"John Doe",
        "accountNumber":"2345678",
        "sortCode":"123456"
    }
}

Request body with IBAN and BIC

{   "customerIdentifier": "1234567",
    "paymentGiro": "FPS", 
    "amount": "0.01",
    "currency": "GBP",
    "reference": "{{randomString}}",
    "customerBankAccount":{
        "type":"IbanAndBic",
        "bankAccountHolderName":"John Doe",
        "iban":"DE12345678",
        "bic":"NTSBDEB1XXX"
    }
}

Body - Additional Optional Fields

key	Description	Values	Example
searchableText	This parameter will be shown in the Admin Dashboard and merchants can search on this field. This is used in cases where merchant systems have important ids which your staff may wish to use to find Pay-ins	String	"SomeID"
payload	This is cargo data and is passed through the Yaspa system and returned on the Webhooks	String	"SomePayload"
KYC Data See link for details	A range of KYC data that helps Yaspa to highlight fraud and add further insights to payments.	See Link	https://docs.yaspa.com/docs/instant-payouts-additional-features#kyc-data-1
customerIpAddress	This allows us to locate the user and understand what country they are from	String	"203.0.113.42"
customerDeviceOs	The device OS the user is on, this helps with troubleshooting.	String	iOS, Android or Chrome etc
payloadEncrypted	Request to encrypt the payload	boolean	true or false
promoCode	Where the payment can be attributed to a promotional bonus the promo code can be passed to Yaspa who can provide insights on the trends around specific codes.	String	"Welcome200"

API Response

Response Body

The response body will contain the Payout transaction details.

Example:

{   "id": "68a57f792a291c45eac1ec15",
    "citizenTransactionId": "Uijjv6o9fje6F3inaF",
    "merchantId": "67fe73696a9ea33c061f0430",
    "merchantTradingName": "MERCHANT_NAME",
    "customerIdentifier": "CUSTOMERID123",
    "version": "2",
    "authType": "STANDARD",
    "transactionStatus": "QUEUED",
    "isPayloadEncrypted": false,
    "creationDate": 1755676537904,
    "testParameters": {},
    "language": "en",
    "isVerifiedJourney": false,
    "citizenCounterPartyId": "68a57f7a2a291c45eac1ec16",
    "currency": "EUR",
    "paymentGiro": "SEPA_INSTANT",
    "merchantBankCode": "XV2XzDBYAX619wwZkg4iOawZcDwSY5Mp",
    "merchantAccountNumber": "SVrgqyRffBoIKXRU2MKfKEbHJ39aE3fUFqiCScD/U2PHicA8XDY=",
    "merchantBank": "SETTLEMENT_BANK",
    "counterPartyBank": "BANK_NAME",
    "counterPartyBankCode": "XF2O1jBYAX5yzPEzEJ7A8GmmxZ/3JiYP",
    "counterPartyAccountNumber": "TESTVfZQAJIHVa38KXLEXDK35TEkHL/PfAGAl0my3fu//4tA4=",
    "counterPartyAccountName": "YASPATestAccount Holder",
    "amount": 0.01,
    "reference": "jlTzbmj2rm81",
}

At this point the Payout has been submitted and if it's queued the Payout will be awaiting approval, otherwise it will have been submitted to the merchant bank.