Payments

This tutorial walks you through each of the steps required to complete an Open Banking payment using Yapily.

In this tutorial we are going to create a UK Domestic Single Payment with Lloyds Sandbox. Each step will be summarised with further reading available for additional more detailed information.

1 Get Institutions
2 Authorisation
3 Create the payment
4 Get Status


1. Get Institutions

Optional - this step is optional as it is entirely possible to make a payment without retrieving the institutions, however it is often required to display a list of supported banks for your customer to choose which bank they would like to make the payment from.

Request:

curl https://api.yapily.com/institutions -u API_KEY:API_SECRET

Response:

{
    "data": [{
        "id": "lloyds-sandbox",
        "name": "Lloyds Bank Sandbox",
        "fullName": "Lloyds Bank Sandbox",
        "countries": [{
            "displayName": "United Kingdom",
            "countryCode2": "GB"
        }],
        "environmentType": "SANDBOX",
        "credentialsType": "OPEN_BANKING_UK_MANUAL",
        "media": [{
            "source": "https://images.yapily.com/image/170bd6f9-4716-43d7-b9cc-af19d606857c?size=0",
            "type": "icon"
        }, {
            "source": "https://images.yapily.com/image/cc5d6705-483d-4598-986f-ef8fd072ed7f?size=0",
            "type": "logo"
        }],
        "features": [
            "ACCOUNT_PERIODIC_PAYMENTS",
            "INITIATE_DOMESTIC_SINGLE_PAYMENT",
            "ACCOUNT",
            "EXISTING_PAYMENT_INITIATION_DETAILS",
            "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
            "INITIATE_ACCOUNT_REQUEST",
            "CREATE_DOMESTIC_SINGLE_PAYMENT",
            "ACCOUNT_REQUEST_DETAILS",
            "ACCOUNT_TRANSACTIONS",
            "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
            "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
            "ACCOUNTS",
            "ACCOUNT_SCHEDULED_PAYMENTS",
            "CREATE_DOMESTIC_PERIODIC_PAYMENT",
            "IDENTITY",
            "ACCOUNT_DIRECT_DEBITS",
            "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
            "EXISTING_PAYMENTS_DETAILS"
        ]
    }],
    "meta": {
        "tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
        "count": 1
    }
}

  • 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 feature ​CREATE_DOMESTIC_SINGLE_PAYMENT.

  • In your app, you should ask the user to select the bank they wish to make the payment from.

  • Once selected, the Institution id should be passed in the next step.

Further reading ↗


2. Authorisation

Now that you have the ​institution-id ​and are confident 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.

Request:

curl https://api.yapily.com/payment-auth-requests \
  -H 'Content-Type: application/json' \
  -u API_KEY:API_SECRET \
  -d '{
    "applicationUserId": "single-payment-tutorial",
    "institutionId": "lloyds-sandbox",
    "callback": "https://display-parameters.herokuapp.com/",
    "paymentRequest": {
        "type": "DOMESTIC_PAYMENT",
        "reference": "Bills Coffee Shop",
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "amount": {
            "amount": "8.70",
            "currency": "GBP"
        },
        "payee": {
            "name": "BILLS COFFEE LTD",
            "accountIdentifications": [{
                "type": "ACCOUNT_NUMBER",
                "identification": "99998888"
            },{
                "type": "SORT_CODE",
                "identification": "556677"
            }]
        }
    }
}'

Response:

{
    "data": {
        "id": "d73e6ac2-31af-4952-9caa-4a58281533ae",
        "userUuid": "3d89197c-659f-4b90-bc0d-f63981417b1f",
        "applicationUserId": "single-payment-tutorial",
        "institutionId": "lloyds-sandbox",
        "status": "AWAITING_AUTHORIZATION",
        "createdAt": "2021-02-13T17:59:13.895Z",
        "featureScope": ["EXISTING_PAYMENT_INITIATION_DETAILS", "EXISTING_PAYMENTS_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT"],
        "state": "a86a5191018d42e092795e392a8697d7",
        "institutionConsentId": "PDC_fc92cf6f-c534-46a0-8a5e-b06411ff04d5",
        "authorisationUrl": "{authorisationUrl}",
        "qrCodeUrl": "https://images.yapily.com/image/bc95f11c-4c99-47b5-a841-b19f3c9c71b3/1613239154?size=0"
    },
    "meta": {
        "tracingId": "43fb7c8b3712f0daeedc62e9e1b22cb8"
    }
}
  • 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: llr001 / Password123.

  • Upon completion the user will be redirected back to the callback url supplied in the request. In our example we are using https://display-parameters.herokuapp.com/, which will display the parameters returned with the redirect. The most important of which is the consent, which is used in the next step to trigger the authorised payment.

Further reading ↗


3. Create the payment

Now the user has authorised the payment request and you have the consentToken, you are able to execute the payment. To do this, you will need to send a ​Create Payment​ request with the same ​paymentRequest object specified in step 2 as the request body.

Request:

curl https://api.yapily.com/payments \
  -H 'Content-Type: application/json' \
  -H 'consent: {consentToken}' \
  -u API_KEY:API_SECRET \
  -d '{
    "type": "DOMESTIC_PAYMENT",
    "reference": "Bills Coffee Shop",
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "amount": {
        "amount": "8.70",
        "currency": "GBP"
    },
    "payee": {
        "name": "BILLS COFFEE LTD",
        "accountIdentifications": [{
            "type": "ACCOUNT_NUMBER",
            "identification": "99998888"
        },{
            "type": "SORT_CODE",
            "identification": "556677"
        }]
    }
}'

Response:

{
    "data": {
        "id": "PDC_fc92cf6f-c534-46a0-8a5e-b06411ff04d5",
        "institutionConsentId": "PDC_fc92cf6f-c534-46a0-8a5e-b06411ff04d5",
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d",
        "status": "PENDING",
        "statusDetails": {
            "status": "PENDING",
            "statusUpdateDate": "2021-02-13T17:59:13.798Z"
        },
        "payeeDetails": {
            "name": "BILLS COFFEE LTD",
            "accountIdentifications": [{
                "type": "ACCOUNT_NUMBER",
                "identification": "99998888"
            }, {
                "type": "SORT_CODE",
                "identification": "556677"
            }]
        },
        "reference": "Bills Coffee Shop",
        "amount": 8.70,
        "currency": "GBP",
        "amountDetails": {
            "amount": 8.70,
            "currency": "GBP"
        },
        "createdAt": "2021-02-13T17:59:13.823Z"
    },
    "meta": {
        "tracingId": "a41f0f7fe8df2ef5667feb47527cd3e7"
    }
}

  • The PaymentResponse returned includes the status and the id. The status of PENDING indicates the request is being processed but is not yet COMPLETED.

  • UK Single Domestic Payments are executed through the Faster Payments Scheme so you can expect the payment to transition from PENDING to ​COMPLETED after a few seconds. This signals that the funds have been credited to your bank account.

  • If you receive the PENDING​ ​status​, you will need to poll the payment ​status​ until it transitions to COMPLETED ​using ​Get Payment Details​ and the ​payment-id​. For more information on managing the payment ​status​ see ​Payments Status​.

Further reading ↗


4. Get the Payment Status

Optional - when the result of the Create Payment request is 'PENDING', you will need to periodically call the Get Payment Details endpoint for the final result.

Request:

curl https://api.yapily.com/payments/PDC_8ea6160a-d257-4925-828b-3bf766858324/details \
    -H 'consent: {consentToken}' \
    -u API_KEY:API_SECRET

Response:

{
    "data": {
        "payments": [{
            "id": "PDC_8ea6160a-d257-4925-828b-3bf766858324",
            "institutionConsentId": "PDC_8ea6160a-d257-4925-828b-3bf766858324",
            "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
            "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d",
            "status": "COMPLETED",
            "statusDetails": {
                "status": "COMPLETED",
                "statusUpdateDate": "2021-02-14T07:58:50.207Z"
            },
            "payeeDetails": {
                "name": "BILLS COFFEE LTD",
                "accountIdentifications": [{
                    "type": "ACCOUNT_NUMBER",
                    "identification": "99998888"
                }, {
                    "type": "SORT_CODE",
                    "identification": "556677"
                }]
            },
            "reference": "Bills Coffee Shop",
            "amount": 8.70,
            "currency": "GBP",
            "amountDetails": {
                "amount": 8.70,
                "currency": "GBP"
            },
            "createdAt": "2021-02-14T07:58:50.232Z"
        }]
    },
    "meta": {
        "tracingId": "44f661ac04ea3163adc3fcf64da8bc80"
    }
}

  • 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.

Further reading ↗


Congratulations, if you got this far, you've just created an Open Banking payment via Yapily.

Next Steps

You might want to check out one of these tutorials: