# Embedded authentication flow

In most cases, banks support users authenticating in the bank's UI/domain. However, there are some scenarios where the bank requires the TPP to capture the fields needed for user authentication. This user experience is referred to as embedded authentication.

See the [Token.io API reference](../../api/reference) for details of the following endpoints used in this integration flow:

- [GET /v2/banks](../../api/reference/Banks-v2#operation/GetBanksv2)
- [POST /v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment)
- [POST v2/payments/{paymentId}/embedded-auth](../../api/reference/Payments-v2#operation/ProvideEmbeddedFields)


Click the image on the right to view a simplified swim lane diagram of the integration flow.

### 1.  TPP retrieves list of banks

TPPs retrieve the list of available banks using the [GET /v2/banks](../../api/reference/Banks-v2#operation/GetBanksv2) call.

We recommend that this step is performed once daily, outside any payment initiation, *e.g*., at 11pm UTC, and that the result is cached.

In the [GET /v2/banks](../../api/reference/Banks-v2#operation/GetBanksv2) request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID.

See [Mandatory fields](../../sip-v2-bank-selection-v2#mandatory-fields) for information on which fields must be provided for a given bank to accept a payment initiation request.

a.  **TPP -> Token.io** - The TPP requests the list of banks from Token.io.

b.  **Token.io -> TPP** - Token.io supplies the list of banks to the TPP.

### 2.  User selects bank

The user selects the bank.

a.  **TPP -> User** - The TPP displays the bank selection screen.

b.  **User -> TPP** - The user selects the bank.

### 3.  TPP accepts consent from user

The TPP accepts consent from the user. For more information see [User consent collection](../../integration-considerations/user-consent-collection).

a.  **TPP -> User** - The TPP initiates consent acceptance from the user.

b.  **User -> TPP** - The user gives consent to the TPP.

The TPP may need to capture additional [mandatory fields](./sip-v2-bank-selection#mandatory-fields) and initial credential information from the user for successful authentication and authorization with the bank.

### 4.  TPP sends initial credentials with payment request

The TPP sends the `initialEmbeddedAuth` fields defined in the [GET /v2/banks](../../api/reference/Banks-v2#operation/GetBanksv2) call using the [POST /v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment) call.

a.  **TPP -> Token.io** - The TPP creates the payment initiation request using the [POST /v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment) call.

If you're using Settlement accounts and you're an unregulated TPP, you'll always need to send the [SettlementAccountId](../../api/reference/Payments-v2#operation/InitiatePayment!path=initiation/creditor/8/SettlementAccountId&t=request) of the sub-TPP in the [POST /v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment) request.

b.  **TPP -> Token.io** - The TPP sends the initial credentials fields with the [POST /v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment) request in the [initialEmbeddedAuth](../../api/reference/Payments-v2#operation/InitiatePayment!path=initialEmbeddedAuth&t=request) field.

c.  **Token.io -> TPP** - Token.io generates a response to the payment initiation request.

If you're subscribed to webhooks, Token.io sends the payment status in a webhook every time a payment is created or updated.

See [Webhooks](./sip-v2-webhooks#payments-v2) for an example webhook notification.

### 5.  TPP captures additional user credentials

If the payment status is `INITIATE_PAYMENT_EMBEDDED_AUTH` then the TPP captures additional credentials from the user using the [POST v2/payments/{paymentId}/embedded-auth](../../api/reference/Payments-v2#operation/ProvideEmbeddedFields) call.

a.  **TPP -> User** - The TPP initiates the collection of additional credentials from the user.

b.  **User -> TPP** - The user provides credential fields to the TPP.

### 6.  TPP submits additional user credentials to bank

Using the [POST v2/payments/{paymentId}/embedded-auth](../../api/reference/Payments-v2#operation/ProvideEmbeddedFields) endpoint, the TPP submits the additional credentials to the bank via Token.io.

a.  **TPP -> Token.io** - The TPP sends the credentials to Token.io using the [POST v2/payments/{paymentId}/embedded-auth](../../api/reference/Payments-v2#operation/ProvideEmbeddedFields) endpoint. This endpoint includes the credentials provided by the user when the `pispConsentAccepted` field is set to `true` in the [POST v2/payments](../../api/reference/Payments-v2#operation/InitiatePayment) request.

b.  **Token.io -> Bank** - Token.io sends this additional information to the bank.

c.  **Bank -> Token.io** - The bank confirms receipt of the information from Token.io.

### 7.  User completes authorization with bank

The user completes authorization with the bank.

a.  **Bank -> User** - The bank displays the authorization page to the user.

b.  **User -> Bank** - The user authorizes the payment with the bank.

### 8.  TPP consumes callback

The TPP consumes the Token.io callback.

a.  **Token.io -> TPP** - The TPP consumes the [Token.io callback](./sip-v2-api-callback).

If TPP callback is in use, refer to [TPP callback](payments-v2-considerations.htm#TPP_callback) for more details.

Steps 7 and 8 may apply to some banks that have a redirection step at the end of the embedded sequence. However, if the bank is using a full embedded flow then these steps will not occur. Instead, the response from the [POST /v2/payments/{paymentId}/embedded-auth](../../api/reference/Payments-v2#operation/ProvideEmbeddedFields) endpoint will contain the payment status, *i.e.*, it will have the same content as the [GET v2/payments/{paymentId}](../../api/reference/Payments-v2#operation/GetPayment) response.

### 9.  TPP receives payment status

Token.io recommends that TPPs subscribe to webhooks to receive payment status updates. As a fallback, TPPs can also poll Token.io for the current status of an initiated payment request.

a.  **Token.io -> TPP** - Token.io sends the payment status to the TPP in a webhook.

See [Webhooks](./sip-v2-webhooks#payments-v2) for an example webhook notification.

b.  **TPP -> Token.io** - The TPP checks the status with Token.io with the [GET /v2/payments/{paymentId}](../../api/reference/Payments-v2#operation/GetPayment) request.

c.  **Token.io -> TPP** - Token.io confirms the payment status with the [GET /v2/payments/{paymentId}](../../api/reference/Payments-v2#operation/GetPayment) response.

If you're using Settlement accounts and the payment initiation request is successful, once the payment has been reconciled, the status will be `SETTLEMENT_COMPLETED`. Depending on the payment rail used, this can take a while.

If you're not using Settlement accounts, the status will be `INITIATION_COMPLETED`, but this doesn't guarantee that the payment has been settled.

If the status is non-final, *e.g.*, `INITIATION_PROCESSING`, wait for additional webhooks to be sent. If the webhook is not received, use a polling call every 120 mins.

The recommended maximum polling time is 30 days. If the bank doesn't update the status, the status will change to `INITIATION_NO_FINAL_STATUS_AVAILABLE` after 30 days.

See [HTTP errors](../../integration-considerations/api-basics#HTTP_errors) for information on HTTP error status codes.

If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)