Tutorial: Make a bulk payment
The Bulk Payments product is available as a Beta version.
This tutorial walks through how to create a UK domestic bulk payment with the Modelo Sandbox.
1. Select bank
To find which banks support bulk payments use GET institutions to retrieve the list of your supported institutions.
Request:
curl -L -X GET 'https://api.yapily.com/institutions' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
"count": 1
},
"data": [
{
"id": "modelo-sandbox",
"name": "Modelo Sandbox",
"fullName": "Modelo Sandbox",
"countries": [
{
"displayName": "United Kingdom",
"countryCode2": "GB"
}
],
"environmentType": "SANDBOX",
"credentialsType": "OPEN_BANKING_UK_AUTO",
"media": [
{
"source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
"type": "icon"
},
{
"source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
"type": "logo"
}
],
"features": [
"INITIATE_ACCOUNT_REQUEST",
"ACCOUNT_REQUEST_DETAILS",
"EXISTING_PAYMENTS_DETAILS",
"ACCOUNT_BALANCES",
"CREATE_BULK_PAYMENT",
"ACCOUNT_PERIODIC_PAYMENTS",
"ACCOUNT_STATEMENTS",
"INITIATE_BULK_PAYMENT",
"ACCOUNT_STATEMENT",
"ACCOUNT",
"INITIATE_DOMESTIC_PERIODIC_PAYMENT",
"INITIATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_DIRECT_DEBITS",
"ACCOUNTS",
"ACCOUNT_TRANSACTIONS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_SINGLE_PAYMENT",
"INITIATE_DOMESTIC_SINGLE_PAYMENT",
"ACCOUNT_STATEMENT_FILE",
"CREATE_INTERNATIONAL_SINGLE_PAYMENT",
"IDENTITY",
"CREATE_DOMESTIC_SCHEDULED_PAYMENT",
"INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
"CREATE_SINGLE_PAYMENT_SORTCODE",
"ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
"INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
"PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
"ACCOUNT_SCHEDULED_PAYMENTS",
"CREATE_DOMESTIC_PERIODIC_PAYMENT"
]
}
]
}
Filter the list for all institutions that support the feature CREATE_BULK_PAYMENT
. Then display these institutions in your application so the user can select which bank to make the payment from.
Once the user selects a bank, store the id
of the institution to use in step 2.
2. Authorisation
After obtaining the institution-id
and confirming that the bank supports the ability to make a domestic bulk payment,
the next step is to generate an authorisation-url
that is used to redirect the user to their chosen bank and to
authorise the payment request.
To do this, execute Create Bulk Payment Authorisation:
Request:
curl -L -X POST 'https://api.yapily.com/bulk-payment-auth-requests' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"applicationUserId": "bulk-payment-tutorial",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/",
"paymentRequest": {
"payments": [
{
"type": "DOMESTIC_PAYMENT",
"reference": "Payment 1",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
],
"address": {
"country": "GB"
}
}
},
{
"type": "DOMESTIC_PAYMENT",
"reference": "Payment 2",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
],
"address": {
"country": "GB"
}
}
}
]
}
}'
Response:
{
"meta": {
"tracingId": "611f74cb4f3205d983ebb2fca59d0847"
},
"data": {
"id": "af563bac-e50a-42bd-91bc-581813e13733",
"userUuid": "f3be3c23-bd0e-475e-b389-62dd1f5aa6c1",
"applicationUserId": "bulk-payment-tutorial",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-03-03T09:23:45.841Z",
"featureScope": [
"EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_BULK_PAYMENT"
],
"state": "6b07bddf9e7746ae8ecb7cbecc00f19a",
"institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
"authorisationUrl": "{authorisationUrl}",
"qrCodeUrl": "https://images.yapily.com/image/55b6b6bc-daa8-490c-89e1-243156868e00/1614763426?size=0"
}
}
-
The
PaymentAuthorisationRequestResponse
returned includes the
authorisationUrl
that you should redirect the user to. -
The user will be asked to login and authorise the payment with their bank. For this tutorial we use the
sandbox credentials
:
mits
/mits
. -
Upon completion the user will be redirected back to the
callback
url supplied in the request. In our example we are usinghttps://display-parameters.com/
, which will display the parameters returned with the redirect. The most important of which is theconsentToken
, which is used in the next step to initiate the authorised payment.
3. Create the payment
Once the user authorises the payment request and you have the consentToken
, you are able to execute the payment.
To do this, execute Create Bulk Payment using the same paymentRequest
object
specified in step 2 as the request body.
Request:
curl -L -X POST 'https://api.yapily.com/bulk-payments' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"payments": [
{
"type": "DOMESTIC_PAYMENT",
"reference": "Payment 1",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
],
"address": {
"country": "GB"
}
}
},
{
"type": "DOMESTIC_PAYMENT",
"reference": "Payment 2",
"paymentIdempotencyId": "{uniqueValue}",
"amount": {
"amount": 8.70,
"currency": "GBP"
},
"payee": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
],
"address": {
"country": "GB"
}
}
}
]
}'
Response:
{
"meta": {
"tracingId": "0cda48c70f3941148bbee775a65fa3d0"
},
"data": {
"id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
"institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
"status": "PENDING",
"statusDetails": {
"status": "PENDING",
"statusUpdateDate": "2021-06-09T13:53:28.67Z"
},
"createdAt": "2021-06-09T13:53:28.67Z",
"bulkAmountSum": 7
}
}
-
The
PaymentResponse
returned includes the
status
and theid
. Thestatus
ofPENDING
indicates the request is being processed but is not yetCOMPLETED
. -
COMPLETED
indicates that theInstitution
has accepted the payment initiation request and will later proceed with settlement -
If you receive the
PENDING
status
, you can use thepayment-id
to poll the paymentstatus
until it transitions toCOMPLETED
orFAILED
.
4. Payment Confirmation
Optional - When the status
of the payment is PENDING
, you will need to monitor the status until the payment
transitions to COMPLETED
confirming that the Institution
has accepted the payment initiation request.
To do this, execute Get Payment Details:
Request:
curl -L -X GET 'https://api.yapily.com/payments/pv3-6c0f031d-6786-4845-9799-bdd2e89ba362/details' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
Response:
{
"meta": {
"tracingId": "0cda48c70f3941148bbee775a65fa3d0"
},
"data": {
"id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
"institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
"status": "COMPLETED",
"statusDetails": {
"status": "COMPLETED",
"statusUpdateDate": "2021-06-09T13:53:28.67Z"
},
"createdAt": "2021-06-09T13:53:28.67Z",
"bulkAmountSum": 7
}
}
-
The
PaymentResponse
returned is exactly the same as the response from the Create Bulk Payment request with the exception that the status may have been updated.
Congratulations! You've just created an Open Banking bulk payment via Yapily.