Embedded Payment 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
- 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
username
and password
of the user to
the Institution
as body parameters. The status
of the Consent
will be AWAITING_SCA_CODE
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
}
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the scaCode
. If successful, the status
of the Consent
will transition to AUTHORIZED
and the response will include the consent-token
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": "{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"
}
}
consent-token
(provided that the status is AUTHORIZED
)
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
in step 3, however, this step is still required to obtain the payment-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"
}
}
}
consent-token
along with the payment-id
from the response of the previous request to check the status
of the payment using
GET Payment Details
Coupled Embedded Payment Flow (Multiple SCA Methods)
Expand/Close Explanation
username
and password
of
the user to the Institution
as body parameters. Yapily will respond with the various SCA methods that the Institution
supports and the status
of the Consent
will be AWAITING_SCA_METHOD
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
]
}
}
Institution
supports to the user in your application
consent-id
returned in the response in step 1 and the sca_methodId
. If successful, the status
of the Consent
will transition to AWAITING_SCA_CODE
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
}
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the scaCode
. If successful, the status
of the Consent
will transition to AUTHORIZED
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
in step 5, however, this step is still required to obtain the payment-id
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
{
"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"
}
}
}
consent-token
along with the payment-id
from the response of the previous request to check the status
of the payment using
GET Payment Details
Decoupled Embedded Payment Flow (Single SCA method)
Expand/Close Explanation
username
and password
of the user to
the Institution
as body parameters. The status
of the Consent
will be AWAITING_SCA_CODE
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
}
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the scaCode
. If successful, the status
of the Consent
will transition to AWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
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 the consent-token
is available, otherwise, poll the status of the Consent
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
{
"meta": {
"tracingId": "187d8fc6dceb4d56bb126f9a9e1b08ba"
},
"data": {
"id": "2523192112221120259PSDLT-BL-LB002045PA9545RW",
"status": "PENDING",
"statusDetails": {
"status": "PENDING"
}
}
}
consent-token
along with the payment-id
from the response of the previous request to check the status
of the payment using
GET Payment Details
Decoupled Embedded Payment Flow (Multiple SCA Methods)
Expand/Close Explanation
username
and password
of
the user to the Institution
as body parameters. Yapily will respond with the various SCA methods that the Institution
supports and the status
of the Consent
will be AWAITING_SCA_METHOD
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
]
}
}
Institution
supports to the user in your application
consent-id
returned in the response in step 1 and the sca_methodId
. If successful, the status
of the Consent
will transition to AWAITING_SCA_CODE
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
}
Institution
will send the SCA code to the user directly. You will need to provide an input field to capture this in your
application
consent-id
returned in the response in step 1 along with the scaCode
. If successful, the status
of the Consent
will transition to
AWAITING_DECOUPLED_AUTHORIZATION
until the user authorises the request on their device
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
}
{
"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"
}
}
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 the consent-token
is available, otherwise, poll the status of the Consent
consent-token
consent-token
to initiate the payment using POST Create Payment. Unlike other flows, the payment is
actually executed by the Institution
once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
Expand/Close Request/Response Example
Request
Response
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"
}
]
}
}
{
"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"
}
}
}
consent-token
along with the payment-id
from the response of the previous request to check the status
of the payment using
GET Payment Details