Tutorial: Make a single UK domestic payment
This tutorial walks through how to create a UK Domestic Single Payment with the Modelo Sandbox. Each step contains links to further reading for more detailed information.
1. Get Institutions
Optional - This step is optional as it is entirely possible to access account data without retrieving the Institution
list,
however it is often required to display a list of supported banks for your customer to choose which bank they would like
to share their data from.
Note: All requests made to the Yapily API require basic authentication.
To display this list, use GET Institutions:
Request:
curl --location --request GET 'https://api.yapily.com/institutions' \
--header 'Authorization: Basic {authToken}'
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"
]
}
]
}
-
Each
Institution
returned contains a logo, name, id and a list of supported features. As we want to allow the customer to perform a UK Domestic Single Payment, we can offer any institution that supports the featureCREATE_DOMESTIC_SINGLE_PAYMENT
. - This information can be leveraged in a third party application to allow the user to select the bank they wish to make the payment from.
-
Once the user selects a bank, the
id
Institution should be stored to use in the next step.
2. Authorisation
After obtaining the institution-id
and confirming that the bank supports the ability to make a domestic 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 Payment Authorisation:
Request:
curl --location --request POST 'https://api.yapily.com/payment-auth-requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {authToken}' \
--data-raw '{
"applicationUserId": "single-payment-tutorial",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/",
"paymentRequest": {
"type": "DOMESTIC_PAYMENT",
"reference": "Bills Coffee Shop",
"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": "single-payment-tutorial",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-03-03T09:23:45.841Z",
"featureScope": [
"EXISTING_PAYMENTS_DETAILS",
"CREATE_DOMESTIC_SINGLE_PAYMENT",
"EXISTING_PAYMENT_INITIATION_DETAILS"
],
"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 Payment using the same paymentRequest
object
specified in step 2 as the request body.
Request:
curl --location --request POST 'https://api.yapily.com/payments' \
--header 'Content-Type: application/json' \
--header 'Consent: {consentToken}' \
--header 'Authorization: Basic {authToken}' \
--data-raw '{
"type": "DOMESTIC_PAYMENT",
"reference": "Bills Coffee Shop",
"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": "0f07ebe9be5fbec0dd660c4e091bd181"
},
"data": {
"id": "pv3-6c0f031d-6786-4845-9799-bdd2e89ba362",
"institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
"paymentIdempotencyId": "{uniqueValue}",
"paymentLifecycleId": "69d55454ea74546e8b1b44efb17fc45",
"status": "PENDING",
"statusDetails": {
"status": "PENDING",
"isoStatus": {
"code": "PDNG",
"name": "Pending"
}
"statusUpdateDate": "2021-03-03T09:41:48.253Z"
},
"payeeDetails": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"reference": "Bills Coffee Shop",
"amount": 8.70,
"currency": "GBP",
"amountDetails": {
"amount": 8.70,
"currency": "GBP"
},
"createdAt": "2021-03-03T09:41:48.253Z"
}
}
-
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 --location --request GET 'https://api.yapily.com/payments/pv3-6c0f031d-6786-4845-9799-bdd2e89ba362/details' \
--header 'Content-Type: application/json' \
--header 'Consent: {consentToken}' \
--header 'Authorization: Basic {authToken}'
</code></pre>
Response:
<pre><code class="language-json">
{
"meta": {
"tracingId": "70c912118c3364f98f1c9dec073c3443"
},
"data": {
"payments": [
{
"id": "pv3-6c0f031d-6786-4845-9799-bdd2e89ba362",
"institutionConsentId": "sdp-1-469c63ef-e6b6-4dd2-88b7-3aea0bff4136",
"paymentIdempotencyId": "{uniqueValue}",
"paymentLifecycleId": "69d55454ea74546e8b1b44efb17fc45",
"status": "COMPLETED",
"statusDetails": {
"status": "COMPLETED",
"isoStatus": {
"code": "ACTC",
"name": "AcceptedTechnicalValidation"
}
"statusUpdateDate": "2021-03-03T09:41:48.253Z"
},
"payeeDetails": {
"name": "BILLS COFFEE LTD",
"accountIdentifications": [
{
"type": "ACCOUNT_NUMBER",
"identification": "{accountNumber}"
},
{
"type": "SORT_CODE",
"identification": "{sortCode}"
}
]
},
"reference": "Bills Coffee Shop",
"amount": 8.70,
"currency": "GBP",
"amountDetails": {
"amount": 8.70,
"currency": "GBP"
},
"createdAt": "2021-03-03T09:41:48.253Z"
}
]
}
}
-
The
PaymentResponse
returned is exactly the same as the response from the Create Payment request with the exception that the status may have been updated.
Congratulations! You've just created a single domestic payment via Yapily.