Tutorial: Make a single payment
This tutorial walks through how to create a UK domestic single payment with the Modelo Sandbox.
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 -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"
]
}
]
}
-
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 -L -X POST 'https://api.yapily.com/payment-auth-requests' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"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}"
}
]
}
}
}'
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 -L -X POST 'https://api.yapily.com/payments' \
-H 'Content-Type: application/json' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
"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}"
}
]
}
}'
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.
You can do that by either polling payment details or setting up a webhook notification
To get payment details manually, 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": "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.