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 the INITIATE_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)

Authorisation_Flows-Embedded_Payments_singSCA

Expand/Close Explanation

You will need to execute POST Create Embedded Payment Authorisation supplying the 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


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 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"
    }
}

You can also execute GET Consent to obtain the consent-token (provided that the status is AUTHORIZED)

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 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"
        }
    }
}

You will also be able to use the 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)

Authorisation_Flows-Embedded_Payments_MultiSCA

Expand/Close Explanation

You will need to execute POST Create Embedded Payment Authorisation supplying the 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


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 the sca_methodId. If successful, the status of the Consent will transition to AWAITING_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 the scaCode. If successful, the status of the Consent will transition to AUTHORIZED

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 the Institution in step 5, 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": "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 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)

Authorisation_Flows-Embedded_Payments_singSCA

Expand/Close Explanation

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


    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 the consent-token is available, otherwise, poll the status of the Consent
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 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


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 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)

Authorisation_Flows-Embedded_Payments_MultiSCA

Expand/Close Explanation

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

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

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": "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 the consent-token is available, otherwise, poll the status of the Consent
You will then need to execute GET Consent to obtain the consent-token

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 the payment-id from the response of the previous request to check the status of the payment using GET Payment Details