Payment workflow


All the non-inquiry operations require a Strong Customer Authentication. This means that these operations must be split in more than one API; there should be:

  • one or more steps to insert the required operation data
  • a process, composed of a certain number of steps, to implement the 2-factor authentication. In this process, the exact operation inserted will be authorized
  • one final steps which will actually execute the operation inserted (if and only if it's authorized) We adopted a standard naming for the types of the API involved in this process:

  • GET .../< OPERATION_NAME >/prepare → (optional) this API returns generic information/suggestions about the operation to execute (e.g. the allowed dates, allowed recipient nations...), which will be useful to compose the request to the subsequent APIs. You can avoid to call it, since all the subsequent APIs integrate the input validation
  • POST .../< OPERATION_NAME >/verify → the first API in which the user passes the operation data. This API creates a transaction resource, and it returns the resourceId field in response
  • PUT .../< OPERATION_NAME >/{resourceId}/verify< NUMBER > → potential other APIs that insert additional operation data (the majority of operations do not have this type of API in the flow). The resourceId is the one created by the API above, the NUMBER is an incremental number, to distinguish the position in the flow
  • PUT .../< OPERATION_NAME >/{resourceId}/execute → the final API, which actually executes the operation; this API generally does not have parameters (the ones saved by the first API in the flow will be used)

The operation flow is guided by the HAL structure in the API responses. So what you will see is (bank transfer example, but you can apply to every operation):

Prepare data

.../< OPERATION_NAME >/prepare - response

{
    ...
    "_links": {
        "next": {
            "href": "verify",
            "method": "POST"
        },
        "self": {
            "href": "prepare",
            "method": "GET"
        },
        "curies": [{
            "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/products/<PRODUCT_ID>/moneyTransfer/{rel}",
            "name": "moneyTransfer"
        }]
    },
    "_embedded": {

    }
    ...
}
Insert and validate data

.../< OPERATION_NAME >/verify - response

{
    ...
    "resources": {
        "resourceId": "5e8134cc-401d-48a6-9f6c-26d0711c7c36"
    },
    "_links": {
        "next": {
            "href": "5e8134cc-401d-48a6-9f6c-26d0711c7c36/execute",
            "method": "PUT"
        },
        "self": {
            "href": "verify",
            "method": "POST"
        },
        "curies": [{
            "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/products/<PRODUCT_ID>/moneyTransfer/{rel}",
            "name": "moneyTransfer"
        }]
    },
    "_embedded": {
        "security": {
            "href": "https://external-api.chebanca.io/private/auth/security/5e8134cc-401d-48a6-9f6c-26d0711c7c36/verify",
            "method": "PUT"
        }
    }
    ...
}
Execute operation

.../< OPERATION_NAME >/{resourceId}/execute - response

{
    ...
    "resources": {
        "resourceId": "5e8134cc-401d-48a6-9f6c-26d0711c7c36"
    },
    "_links": {
        "self": {
            "href": "5e8134cc-401d-48a6-9f6c-26d0711c7c36/execute",
            "method": "PUT"
        },
        "curies": [{
            "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/products/<PRODUCT_ID>/moneyTransfer/{rel}",
            "name": "moneyTransfer"
        }]
    },
    "_embedded": {
        "printer": {
            "href": "https://external-api.chebanca.io/private/customers/<CUSTOMER_ID>/products/<PRODUCT_ID>/common/printer/5e8134cc-401d-48a6-9f6c-26d0711c7c36/retrieve",
            "method": "GET"
        }
    }
    ...
}

The 2-factor authentication flow is triggered by an _embedded link named "security" in the response of the last verify API of the flow.

Payment authorization

The /verify API is required to insert the payment data, while the /execute API is the one that actually executes the payment.

In the middle of these APIs, the user needs to authorize the payment. The payment authorization is completely managed by CheBanca! systems, and it's an OAuth-like flow.

In summary, the steps to perform a payment are the following:

  • you, as a third party provider, can call an API to insert the payment data
  • once the API has correctly finished, you have to call the /private/auth/security/sca/{resourceId}/approach API, specifying your preferred SCA approach. This API will return the allowed approach for the payment operation executing (the possible values are REDIRECT or DECOUPLED).
    • in case of REDIRECT approach, the API will return also the redirect URL to which the user must be redirected (browser-side). The user will then log-in to a CheBanca! application and perform the payment authorization
    • in case of DECOUPLED approach, the API will only tell the user to perform the authorization on another channel
  • in both cases, you have to call the /private/operations/{resourceId}/status API (in polling mode) to retrieve the authorization status. When the API returns the authorizationStatus = DONE, you finally can proceed with the payment execution
  • you can call the payment execution API, which will check the authorization status and will execute the payment
  • (optional) if you want, you can call the /private/operations/{resourceId}/status API to get the transaction outcome

Notes

You can find the specific documentation of all the APIs you have to call here