Virtual Accounts sandbox

You can use the Virtual Accounts sandbox to try out features and test your integration.

Access

You can only access the Virtual Accounts sandbox using a specific application. Please contact your Customer Success Manager to create and configure this application for you.

You will be provided with a test client ID which must be provided in the client_id header.

Once setup, you can use this application as you would in production, including connecting to the api.yapily.com base url, but you are only operating on test virtual accounts.

Simulate a Pay In

You can add funds to a sandbox virtual account to simulate a Pay In. You can also test Pay In notifications.

Request

To make the request, specify the desired payment amount and dummy source account details to POST /virtual-accounts/simulator/payments/pay-in. You can provide all, none or some account identifiers in the request.

curl -L -X POST 'https://api.yapily.com/virtual-accounts/simulator/payments/pay-in' \
-H 'client-id: <VIRTUAL_ACCOUNT_CLIENT_ID>' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "accountId": "<VIRTUAL_ACCOUNT_ID>",
   "paymentScheme": "SEPA_CREDIT",
   "amount": {
       "amount": 0.1,
       "currency": "EUR"
   },
   "reference": "Test payment",
   "source": {
       "type": "EXTERNAL",
       "accountIdentifications": [
           {
               "type": "IBAN",
               "identification": "GB29NWBK60161331926819"
           },
           {
               "type": "BIC",
               "identification": "BUKBGB22"
           },
           {
               "type": "ACCOUNT_NUMBER",
               "identification": "31926819"
           },
           {
               "type": "SORT_CODE",
               "identification": "601613"
           }
       ]
   },
   "name": "Jane Doe",
   "address": "1 Sample Street, London"
}'

curl -L -X POST 'https://api.yapily.com/virtual-accounts/simulator/payments/pay-in' \
-H 'client-id: <VIRTUAL_ACCOUNT_CLIENT_ID>' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "accountId": "<VIRTUAL_ACCOUNT_ID>",
   "paymentScheme": "SEPA_CREDIT",
   "amount": {
       "amount": 0.1,
       "currency": "EUR"
   },
   "reference": "Test payment",
   "source": {
       "type": "EXTERNAL",
       "accountIdentifications": []
   },
   "name": "Jane Doe",
   "address": "1 Sample Street, London"
}'

curl -L -X POST 'https://api.yapily.com/virtual-accounts/simulator/payments/pay-in' \
-H 'client-id: <VIRTUAL_ACCOUNT_CLIENT_ID>' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "accountId": "<VIRTUAL_ACCOUNT_ID>",
   "paymentScheme": "SEPA_CREDIT",
   "amount": {
       "amount": 0.1,
       "currency": "EUR"
   },
   "reference": "Test payment",
   "source": {
       "type": "EXTERNAL",
       "accountIdentifications": [
           {
               "type": "IBAN",
               "identification": "GB29NWBK60161331926819"
           }
       ]
   },
   "name": "Jane Doe",
   "address": "1 Sample Street, London"
}'

Validation logic

IBAN, account number and sort code are validated individually by the following requirements:

• The IBAN must start with the country code
• The account number must be 8 digits long
• The sort code must be 6 digits long

When all 3 identifiers are provided they are also validated together by the following requirements:

• The sort code matches the first 6 digits after the letter section of the IBAN
• The account number matches the last 8 digits of the IBAN

Response

If successful, returns a 200 status code. No response body is returned.

You can verify the account balance by calling the Get Virtual Account endpoint.

Update the status of a Pay Out

In the sandbox, the status of any Pay Out you successfully initiate will remain as "PROCESSING" unless you explicitly request for the status to be updated. You may want to do this in order to test Pay Out completion scenarios, including the generation of Pay Out Status notifications.

You can update the Pay Out status by making a request to POST /virtual-accounts/simulator/payments/pay-outs/<PAY_OUT_ID>/status-update.

You must specify the Pay Out ID in the path of the request and the required status value in the body.

Possible status values are: "FAILED" or "COMPLETED".

Example request to update the status to COMPLETED:

curl -L -X POST 'https://api.yapily.com/virtual-accounts/simulator/payments/pay-outs/<PAY_OUT_ID>/status-update' \
-H 'Content-Type: application/json' \
-H 'client-id: <VIRTUAL_ACCOUNT_CLIENT_ID>' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "status": "COMPLETED"
}'

If successful, returns a 200 status code. No response body is returned.

Simulate a Pay Out Return

You can return the funds made in a Pay Out transaction to a sandbox virtual account to simulate a Pay Out Return. You can also test Pay Out Return notifications.

Make a request to POST /virtual-accounts/simulator/payments/<PAY_OUT_ID>/pay-out-return, specifying the ID of the Pay Out that you want to return in the path of the request.

The original transaction is not changed and a new transaction is created of type RETURN_IN.

Note: The Pay Out must have a "COMPLETED" status to be returned.

Example request for a Pay Out Return:

curl -L -X POST 'https://api.yapily.com/virtual-accounts/simulator/payments/<PAY_OUT_ID>/pay-out-return' \
-H 'client-id: <VIRTUAL_ACCOUNT_CLIENT_ID>' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
   "status": "RETURNED",
   "reason": "Transaction returned"
}'

If successful, returns a 200 status code. No response body is returned.

You can verify the returned transaction has been successfully created by calling the Get Payments endpoint.

Note: Payments of type RETURN_IN return an additional field originalPaymentId which corresponds to the ID of the original payment.