Embedded payment authorisation flows
Summary
An Institution
that uses an embedded flow is one where the authorisation takes place without any redirect to the Institution
. This process works by capturing the credentials from the PSU
and sending them to the bank via Yapily. Before the Consent
is authorised, the Institution
will send an scaCode
to the PSU which will similarly have to be captured in your
front-end application and sent back to the Institution
via Yapily.
Identifying each flow
An Institution
that uses the embedded payment authorisation flow:
-
Will have the
INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature - May involve one decoupled payment authorisation step
Notes
-
Use
GET Institutions
to check for each
Institution
that uses theINITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT
feature -
The
redirectUrl
is not used at all in any of these flows so the diagrams are the same for all customers
Single vs. Multiple SCA Methods
It is possible for a PSU to have multiple means for the Institution
to send the scaCode
to them if the Institution
supports it and the PSU has them configured. In this case, after initiating
the embedded payment authorisation with the credentials of the PSU, an additional step is added before the scaCode
is sent to the PSU, where a SCA_METHOD
list is first sent by the Institution
.
Upon receiving this list, you will need to present it the PSU in your front-end in the form of a dropdown menu. When the user selects which SCA_METHOD
they wish the Institution
to use to contact
them, you will send this back to Institution
via Yapily and then the scaCode
will be sent by the Institution
to the PSU.
If the Institution
only supports one SCA_METHOD
or the PSU only has one SCA_METHOD
configured with an Institution
, then initiating the embedded payment authorisation with the credentials of
the PSU will result in the Institution
immediately sending the scaCode
to the PSU.
Coupled Embedded Payment Flow (Single SCA method)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Payment Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Thestatus
of theConsent
will beAWAITING_SCA_CODE
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/embedded-payment-auth-requests \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "userCredentials": { "id": "username", "password": "password" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } } }
Response:
{ "meta": { "tracingId": "12fb2ec383884d40bea8c179d1cdcaa0" }, "data": { "id": "9f64b2fe-be6a-4c23-b5c0-c207691c5dfc", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_CODE", "createdAt": "2021-12-22T10:24:00.190Z", "featureScope": [ "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS", "EXISTING_PAYMENT_INITIATION_DETAILS" ], "state": "dc46440dffff497f8c64b7cc64772e87", "institutionConsentId": "8199532112221120235PSDLT-BL-LB002045PA9545RW", "scaMethods": [ { "id": "932", "type": "CHIP_OTP", "description": "SmartTAN plus" } ], "selectedScaMethod": { "id": "932", "type": "CHIP_OTP", "description": "SmartTAN plus" } } }
-
When you send the POST request in step 1, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Payment Authorisation
using the
consent-id
returned in the response in step 1 along with thescaCode
. If successful, thestatus
of theConsent
will transition toAUTHORIZED
and the response will include the consent-tokenExpand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instution-id}", "scaCode": "123456", "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } } }
Response:
{ "meta": { "tracingId": "de91d28aff954c97b743f43ac6b23cdd" }, "data": { "id": "a7a19bb7-f9b6-484f-983f-28082cf51827", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AUTHORIZED", "createdAt": "2021-12-22T10:29:13.560Z", "featureScope": [ "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS" ], "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImZpZHVjaWEtc2FuZGJveCIsIkNPTlNFTlQiOiJhN2ExOWJiNy1mOWI2LTQ4NGYtOTgzZi0yODA4MmNmNTE4MjciLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoiZW1iZWRkZWQtcGF5bWVudC1hdXRoLWV4YW1wbGUiLCJVU0VSIjoiZWNjNGM0ZTUtNTBjZC00YmZjLTlhY2EtNmM1M2Q1ODlhZTNiIn0.pVPA65qjUWjCJBHdVG-ZUNjdnmzP8UM_R8q8A_CvKbIy7RFrJWBkzvWLUulkdYl7SeYVo5_8CzY2dPj7LTMg2g", "state": "831294233ecb4d649dc369abbc01077e", "authorizedAt": "2021-12-22T10:29:22.657Z", "institutionConsentId": "2523192112221120259PSDLT-BL-LB002045PA9545RW" } }
-
You can also execute
GET Consent
to obtain the
consent-token
(provided that the status isAUTHORIZED
) -
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment . Unlike other flows, the payment is actually executed by theInstitution
in step 3, however, this step is still required to obtain thepayment-id
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/payments \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'consent: {consentToken}' \ -H 'Authorization: Basic {authToken}' { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" }, ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } }
Response:
{ "meta": { "tracingId": "187d8fc6dceb4d56bb126f9a9e1b08ba" }, "data": { "id": "2523192112221120259PSDLT-BL-LB002045PA9545RW", "status": "COMPLETED", "statusDetails": { "status": "COMPLETED" } } }
-
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Coupled Embedded Payment Flow (Multiple SCA Methods)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Payment Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Yapily will respond with the various SCA methods that theInstitution
supports and thestatus
of theConsent
will beAWAITING_SCA_METHOD
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/embedded-payment-auth-requests \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "userCredentials": { "id": "username", "password": "password" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } } }
Response:
{ "meta": { "tracingId": "eb9aa9e5f5c949d1bd88d238462572cb" }, "data": { "id": "c133245f-cd5d-486b-804d-326354c0a433", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_METHOD", "createdAt": "2021-12-17T08:18:15.056Z", "featureScope": [ "EXISTING_PAYMENTS_DETAILS", "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT" ], "state": "b65ef568080e463f9634fbfb6d373ec5", "institutionConsentId": "13490069-3b15-4894-9bb2-3fb93bf3a133", "charges": [ { "chargeAmount": { "amount": 1.27, "currency": "EUR" } } ], "scaMethods": [ { "id": "258211#OPTICAL", "type": "CHIP_OTP", "description": "Testkarte Hr. Haubach_1, optisch" }, { "id": "258211#MANUEL", "type": "CHIP_OTP", "description": "Testkarte Hr. Haubach_1, manuell" }, { "id": "591655", "type": "SMS_OTP", "description": "RolandmTAN" }, { "id": "591656", "type": "PUSH_OTP", "description": "RSRolandIP2" } ] } }
-
You can use the various sca methods returned by Yapily to populate a dropdown and display the options the
Institution
supports to the user in your application -
After the user selects an SCA method, you will need to execute
PUT Update Embedded Payment Authorisation
using the
consent-id
returned in the response in step 1 and thesca_methodId
. If successful, thestatus
of theConsent
will transition toAWAITING_SCA_CODE
Expand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests\{consent-id} \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "selectedScaMethod": { "id": "258211#OPTICAL", "type": "SMS_OTP" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } } }
Response:
{ "meta": { "tracingId": "48522b10e28f453d8a303ae9ab3cf890" }, "data": { "id": "234f4320-ff1f-4d81-92b7-af9796399b3e", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_CODE", "createdAt": "2021-12-16T10:11:59.854Z", "featureScope": [ "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENT_INITIATION_DETAILS", "EXISTING_PAYMENTS_DETAILS" ], "state": "ae49897ed9764a0da5e596cd8890c838", "institutionConsentId": "9b4bb4b4-41b0-4097-97fb-2b8915599b30", "selectedScaMethod": { "id": "258211#OPTICAL", "type": "SMS_OTP" } } }
-
When you send the PUT request in step 3, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Payment Authorisation
a second time using the
consent-id
returned in the response in step 1 along with thescaCode
. If successful, thestatus
of theConsent
will transition toAUTHORIZED
Expand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "scaCode": "325614", "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } } }
Response:
{ "meta": { "tracingId": "6b04e0504f3546bf928bc6b46b3cba7f" }, "data": { "id": "6cf15c92-bbfa-4532-8738-d7e61b1bec15", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AUTHORIZED", "createdAt": "2021-12-16T10:26:16.340Z", "featureScope": [ "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS", "EXISTING_PAYMENT_INITIATION_DETAILS" ], "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InBvc3RiYW5rLXNhbmRib3giLCJDT05TRU5UIjoiNmNmMTVjOTItYmJmYS00NTMyLTg3MzgtZDdlNjFiMWJlYzE1IiwiQVBQTElDQVRJT05fVVNFUl9JRCI6ImVtYmVkZGVkLXBheW1lbnQtYXV0aC1leGFtcGxlIiwiVVNFUiI6ImVjYzRjNGU1LTUwY2QtNGJmYy05YWNhLTZjNTNkNTg5YWUzYiJ9._FPAqj_dkPz4UhIXOngHEf4PyvRKmGVKl5Ncwi8AcIcB3AyG7wox_omtLkZeunVXnOdEWVaZRdMVYtUiyP0YIw", "state": "a88881275b384b72ac1df285c97ef7f0", "authorizedAt": "2021-12-16T10:27:15.426Z", "institutionConsentId": "2fc7df88-6401-4f08-8400-355fb31e5cde" } }
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment . Unlike other flows, the payment is actually executed by theInstitution
in step 5, however, this step is still required to obtain thepayment-id
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/payments \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'consent: {consentToken}' \ -H 'Authorization: Basic {authToken}' { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } }
Response:
{ "meta": { "tracingId": "a0a0286c6db94831be4c0f98f682b7e7" }, "data": { "id": "13490069-3b15-4894-9bb2-3fb93bf3a133", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "paymentLifecycleId": "d78fy48uh8f9odhde68dfi38di9", "status": "COMPLETED", "statusDetails": { "status": "COMPLETED", "isoStatus": { "code": "ACSC", "name": "AcceptedSettlementCompleted" } }, "payer": { "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "payeeDetails": { "name": "John Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ], "address": { "country": "DE" } }, "reference": "payment1", "amount": 1.0, "currency": "EUR", "amountDetails": { "amount": 1.0, "currency": "EUR" } } }
-
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Decoupled Embedded Payment Flow (Single SCA method)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Payment Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Thestatus
of theConsent
will beAWAITING_SCA_CODE
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/embedded-payment-auth-requests \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "userCredentials": { "id": "username", "password": "password" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } } }
Response:
{ "meta": { "tracingId": "12fb2ec323834d40bea8c179d1c4caa0" }, "data": { "id": "9f64b2fe-be6a-4c23-b5c0-c207691c5dfc", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_CODE", "createdAt": "2021-12-22T10:24:00.190Z", "featureScope": [ "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS", "EXISTING_PAYMENT_INITIATION_DETAILS" ], "state": "dc46440dffff497f8c64b7cc64772e87", "institutionConsentId": "8199532112221120235PSDLT-BL-LB002045PA9545RW", "scaMethods": [ { "id": "932", "type": "CHIP_OTP", "description": "SmartTAN plus" } ], "selectedScaMethod": { "id": "932", "type": "CHIP_OTP", "description": "SmartTAN plus" } } }
-
When you send the POST request in step 1, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Payment Authorisation
using the
consent-id
returned in the response in step 1 along with thescaCode
. If successful, thestatus
of theConsent
will transition toAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their deviceExpand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instution-id}", "scaCode": "123456", "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" }, ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } } }
Response:
{ "meta": { "tracingId": "de91d28aff954c97b743f43ac6b23cdd" }, "data": { "id": "a7a19bb7-f9b6-484f-983f-28082cf51827", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_DECOUPLED_AUTHORIZATION", "createdAt": "2021-12-22T10:29:13.560Z", "featureScope": [ "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS" ], "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImZpZHVjaWEtc2FuZGJveCIsIkNPTlNFTlQiOiJhN2ExOWJiNy1mOWI2LTQ4NGYtOTgzZi0yODA4MmNmNTE4MjciLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoiZW1iZWRkZWQtcGF5bWVudC1hdXRoLWV4YW1wbGUiLCJVU0VSIjoiZWNjNGM0ZTUtNTBjZC00YmZjLTlhY2EtNmM1M2Q1ODlhZTNiIn0.pVPA65qjUWjCJBHdVG-ZUNjdnmzP8UM_R8q8A_CvKbIy7RFrJWBkzvWLUulkdYl7SeYVo5_8CzY2dPj7LTMg2g", "state": "831294233ecb4d649dc369abbc01077e", "authorizedAt": "2021-12-22T10:29:22.657Z", "institutionConsentId": "2523192112221120259PSDLT-BL-LB002045PA9545RW" } }
-
The user will receive an authorisation directly from the
Institution
where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when theconsent-token
is available, otherwise, poll the status of theConsent
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
will then be able to use the
consent-token
to initiate the payment using POST Create Payment . Unlike other flows, the payment is actually executed by theInstitution
once the user has completed the decoupled authorisation, however, this step is still required to obtain thepayment-id
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/payments \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'consent: {consentToken}' \ -H 'Authorization: Basic {authToken}' { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" }, ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } }
Response:
{ "meta": { "tracingId": "187d8fc6dceb4d56bb126f9a9e1b08ba" }, "data": { "id": "2523192112221120259PSDLT-BL-LB002045PA9545RW", "status": "PENDING", "statusDetails": { "status": "PENDING" } } }
-
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details
Decoupled Embedded Payment Flow (Multiple SCA Methods)
Expand/Close Explanation
-
You will need to execute
POST Create Embedded Payment Authorisation
supplying the
username
andpassword
of the user to theInstitution
as body parameters. Yapily will respond with the various SCA methods that theInstitution
supports and thestatus
of theConsent
will beAWAITING_SCA_METHOD
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/embedded-payment-auth-requests \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "userCredentials": { "id": "username", "password": "password" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } } }
Response:
{ "meta": { "tracingId": "eb9aa9e5f5c949d1bd88d238462572cb" }, "data": { "id": "c133245f-cd5d-486b-804d-326354c0a433", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_METHOD", "createdAt": "2021-12-17T08:18:15.056Z", "featureScope": [ "EXISTING_PAYMENTS_DETAILS", "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT" ], "state": "b65ef568080e463f9634fbfb6d373ec5", "institutionConsentId": "13490069-3b15-4894-9bb2-3fb93bf3a133", "charges": [ { "chargeAmount": { "amount": 1.27, "currency": "EUR" } } ], "scaMethods": [ { "id": "258211#OPTICAL", "type": "CHIP_OTP", "description": "Testkarte Hr. Haubach_1, optisch" }, { "id": "258211#MANUEL", "type": "CHIP_OTP", "description": "Testkarte Hr. Haubach_1, manuell" }, { "id": "591655", "type": "SMS_OTP", "description": "RolandmTAN" }, { "id": "591656", "type": "PUSH_OTP", "description": "RSRolandIP2" } ] } }
-
You can use the various sca methods returned by Yapily to populate a dropdown and display the options the
Institution
supports to the user in your application -
After the user selects an SCA method, you will need to execute
PUT Update Embedded Payment Authorisation
using the
consent-id
returned in the response in step 1 and thesca_methodId
. If successful, thestatus
of theConsent
will transition toAWAITING_SCA_CODE
Expand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests\{consent-id} \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "selectedScaMethod": { "id": "258211#OPTICAL", "type": "SMS_OTP" }, "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } } }
Response:
{ "meta": { "tracingId": "48522b10e28f453d8a303ae9ab3cf890" }, "data": { "id": "234f4320-ff1f-4d81-92b7-af9796399b3e", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_SCA_CODE", "createdAt": "2021-12-16T10:11:59.854Z", "featureScope": [ "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENT_INITIATION_DETAILS", "EXISTING_PAYMENTS_DETAILS" ], "state": "ae49897ed9764a0da5e596cd8890c838", "institutionConsentId": "9b4bb4b4-41b0-4097-97fb-2b8915599b30", "selectedScaMethod": { "id": "258211#OPTICAL", "type": "SMS_OTP" } } }
-
When you send the PUT request in step 3, the
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your application -
After the user inputs the SCA code, you will need to execute
PUT Update Embedded Payment Authorisation
a second time using the
consent-id
returned in the response in step 1 along with thescaCode
. If successful, thestatus
of theConsent
will transition toAWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their deviceExpand/Close Request/Response Example
Request:
curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \ -H 'Accept: application/json;charset=UTF-8' \ -H 'Authorization: Basic {authToken}' { "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instution-id}", "scaCode": "123456", "paymentRequest": { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE39499999600000005111" } ] } } }
Response:
{ "meta": { "tracingId": "de91d28aff954c97b743f43ac6b23cdd" }, "data": { "id": "a7a19bb7-f9b6-484f-983f-28082cf51827", "userUuid": "ecc4c4e5-50cd-4bfc-9aca-6c53d589ae3b", "applicationUserId": "embedded-payment-auth-example", "institutionId": "{instutionId}", "status": "AWAITING_DECOUPLED_AUTHORIZATION", "createdAt": "2021-12-22T10:29:13.560Z", "featureScope": [ "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENTS_DETAILS" ], "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImZpZHVjaWEtc2FuZGJveCIsIkNPTlNFTlQiOiJhN2ExOWJiNy1mOWI2LTQ4NGYtOTgzZi0yODA4MmNmNTE4MjciLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoiZW1iZWRkZWQtcGF5bWVudC1hdXRoLWV4YW1wbGUiLCJVU0VSIjoiZWNjNGM0ZTUtNTBjZC00YmZjLTlhY2EtNmM1M2Q1ODlhZTNiIn0.pVPA65qjUWjCJBHdVG-ZUNjdnmzP8UM_R8q8A_CvKbIy7RFrJWBkzvWLUulkdYl7SeYVo5_8CzY2dPj7LTMg2g", "state": "831294233ecb4d649dc369abbc01077e", "authorizedAt": "2021-12-22T10:29:22.657Z", "institutionConsentId": "2523192112221120259PSDLT-BL-LB002045PA9545RW" } }
-
The user will receive an authorisation directly from the
Institution
where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when theconsent-token
is available, otherwise, poll the status of theConsent
-
You will then need to execute
GET Consent
to obtain the
consent-token
-
You will then be able to use the
consent-token
to initiate the payment using POST Create Payment . Unlike other flows, the payment is actually executed by theInstitution
once the user has completed the decoupled authorisation, however, this step is still required to obtain thepayment-id
Expand/Close Request/Response Example
Request:
curl -X POST https://api.yapily.com/payments \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Accept: application/json;charset=UTF-8' \ -H 'consent: {consentToken}' \ -H 'Authorization: Basic {authToken}' { "type": "DOMESTIC_PAYMENT", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "payer": { "name": "Jane Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "amount": { "amount": "1.00", "currency": "EUR" }, "reference": "payment1", "payee": { "name": "John Doe", "address": { "country": "DE" }, "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ] } }
Response:
{ "meta": { "tracingId": "a0a0286c6db94831be4c0f98f682b7e7" }, "data": { "id": "13490069-3b15-4894-9bb2-3fb93bf3a133", "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9", "paymentLifecycleId": "d78fy48uh8f9odhde68dfi38di9", "status": "COMPLETED", "statusDetails": { "status": "COMPLETED", "isoStatus": { "code": "ACSC", "name": "AcceptedSettlementCompleted" } }, "payer": { "accountIdentifications": [ { "type": "IBAN", "identification": "DE90100100100928099103" } ] }, "payeeDetails": { "name": "John Doe", "accountIdentifications": [ { "type": "IBAN", "identification": "DE58648730420109499400" } ], "address": { "country": "DE" } }, "reference": "payment1", "amount": 1.0, "currency": "EUR", "amountDetails": { "amount": 1.0, "currency": "EUR" } } }
-
You will also be able to use the
consent-token
along with thepayment-id
from the response of the previous request to check thestatus
of the payment using GET Payment Details