Instant Payouts - Direct Instruction
Calling the direct payout product API
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 Instant Payout, the merchant will make 2 call Yaspa's HTTPS API Endpoint to generate
Step 1 : Create a Payout Session - API Request
The following call is an HTTPS POST request
- Production - http://api.yaspa.com/v2/payouts/verified/session
- Test Sandbox - http://testapi.yaspa.com/v2/payouts/verified/session
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 | Number | 1.50 |
| paymentGiro | The payment rail to be used for the payment. This must match the currency
| 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 |
| customerIpAddress | IP address of the customer receiving the payout | string with valid IPv4 or IPv6 format | 46.223.81.59 |
| customerDeviceOs | OS for the customer receiving the payout. Note this is just used for analytics. So Unknown can be passed in. | string | Windows, Linux, OSX, IOS, Android, Other, Unknown |
Body - Example body
Below is an example body of a payout instruction.
Please change the reference each time a payout instruction is used.
{
"customerIdentifier": "{{customerIdentifier}}",
"amount": "0.01",
"currency": "EUR",
"customerIpAddress": "46.223.81.59",
"customerDeviceOs": "Unknown",
"paymentGiro": "SEPA",
"reference": "{{randomString}}",
"isQueued": false
}Body - Additional Optional Fields
| key | Description | Values | Example |
|---|---|---|---|
| supportedCountries | This is an array of 2 letter country codes (Iso-3166). The first value in the array is used to set which country banks are shown to the customer by default. Yaspa suggests this is set to the signup country of the customer or simply to the most popular country of the merchant's business. Examples: | String | ["NL"] or ["FR"] |
| successRedirectUrl | This is the URL the merchant wishes the customer to return to after a successful payment. Used on desktop | String | "http://www.merch.com/success" |
| successBankRedirectUrl | This is the URL the merchant wishes the customer to return to after a successful payment. Used on mobile | String | "http://www.merch.com/success" |
| failureRedirectUrl | This is the URL the merchant wishes the customer to return to after a failed payment. Used on desktop | String | "http://www.merch.com/failure" |
| failureBankRedirectUrl | This is the URL the merchant wishes the customer to return to after a failed payment. Used on mobile | String | "http://www.merch.com/failure" |
| language | The 2 letter language code (ISO 639-1) that will be used to display all text in the customer journey. If no language is set or the language isn't supported or recognised, the customers Browser language will be used. | String | "FR" |
| brand | When merchants integrate to Yaspa via a PSP, sometimes the original lobby url is masked. In these cases Yaspa asks the merchant to pass through the lobby url here - this aids support and diagnosis of merchant issues | String | "http://www.merchSiteOne.com" |
| 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 parameter is any JSON object. This is cargo data and is passed through the Yaspa system and returned on the Webhooks | Object | { } |
| description | A description shown on the hosted page to describe what the pay-in is for. | String | "Charitable Donation" |
API Response
Response Body
The response body will contain a citizenTransactionId, this should be kept and used within the Step 2 call
Example:
etffFA9M413uMPNbMfStep 2 : Submit Payout Session - API Request
The following call is an HTTPS POST request
- Production - http://api.yaspa.com/v2/payouts/verified/submit
- Test Sandbox - http://testapi.yaspa.com/v2/payouts/verified/submit
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 |
|---|---|---|---|
| citizenTransactionId | Transaction ID returned when creating the payout session | String | "etffFA9M413uMPNbMf" |
| customerBankAccountId | Customer bank account ID returned when fetching valid bank accounts. | String | "57c8dfb6-dff4-4496-aa3a-4e10f701b93f" |
API Response
Response Body
The response body will contain the Payout transaction details.
Example:
{
"citizenTransactionId":"etffFA9M413uMPNbMf",
"merchantId":"abcedfgh1234",
"merchantTradingName":"Yaspa Test merchant",
"customerIdentifier": "{{randomString}}",
"transactionStatus":"ACCEPTED",
"creationDate":1647010433548,
"testParameters":{},
"citizenCounterPartyId":"622b62816a47c2389498b875",
"providerPaymentId":"296348",
"currency":"GBP",
"paymentGiro":"FPS",
"merchantBankCode":"608384",
"merchantAccountNumber":"40074844",
"merchantBank":"OPENPAYD",
"counterPartyBank":"CITIZEN_TEST_BANK",
"counterPartyBankCode":"040075",
"counterPartyAccountNumber":"57583676",
"counterPartyAccountName":"Yaspa Test Account",
"amount":0.01,
"reference":"{{randomString}}"
}At this point the Payout has been submitting and if its queued the Payout will be awaiting approval, otherwise it will have been submitted to the merchant bank.
Updated about 1 year ago