Initiate a payment

The POST /v2/payments endpoint enables you to initiate a payment with a bank.<br/><br/>Once the payment has been initiated, the end user needs to authenticate themselves with their bank.<br/><br/><b>Check payment status:</b><br/><ol><li>If the status in the initiation response is INITIATION_PENDING_REDIRECT_AUTH or INITIATION_PENDING_REDIRECT_HP, redirect the user to the redirect url found in the authentication payload of the payment, to authenticate at the bank or at Token.io's Hosted Pages.</li><br/><li>If the status in the initiation response is INITIATION_PENDING_REDIRECT_PBL, redirect the user to the payment link (redirect URL) found in the authentication payload. The user will be taken to Token.io’s Hosted Pages, where any missing information (such as amount or reference) can be provided before proceeding with payment authentication.</li><br/><li>If the status in the initiation response is INITIATION_PENDING_EMBEDDED_AUTH, collect the requested data listed in the authentication payload of the payment and use the POST /v2/payments/{paymentId}/embedded-auth endpoint to provide the requested field values.</li><br/><li>If the status in the initiation response is INITIATION_PENDING, Token.io needs more time to process this request with the bank. In the case of a successful scenario, the status will be updated to INITIATION_PENDING_REDIRECT_AUTH, INITIATION_PENDING_EMBEDDED_AUTH or INITIATION_PENDING_DECOUPLED_AUTH when the authentication details are ready. The update can be checked by the GET /v2/payments/{paymentId} endpoint or received via a webhook (see <a href="https://developer.token.io/token_rest_api_doc/content/e-rest/webhooks.htm" target="_blank">Webhooks</a>).</li><br/><li>If the status is INITIATION_PENDING_DECOUPLED_AUTH, the bank has requested a decoupled authentication from the user and Token.io is awaiting the result. No further action is required.</li></ol><br/><b>request-timeout header:</b><br/><br/>Banks may take some time to respond when a request is made. Therefore, Token.io recommends that you set a request-timeout header in your API-only POST /v2/payments requests to match the timeout of your client and avoid DEADLINE_EXCEEDED errors. If this is set, Token.io sends a response when this timeout period has passed and will update payment status as soon as the bank has responded.<br/>The following example demonstrates what happens when you set a timeout of 10 seconds and the call to the bank takes 15 seconds:<br/><br/><ol><li>The TPP makes a POST /v2/payments call.</li><br/><li>Token.io creates a resource with the status INITIATION_PENDING.</li><br/><li>Token.io starts the call to the bank.</li><br/><li>After 10 seconds from (1): Token.io returns the payment status INITIATION_PENDING.</li><br/><li>After 15 seconds from (3): Token.io receives a response from the bank and changes the status to, for example, INITIATION_PENDING_REDIRECT_AUTH. The update will be sent in a webhook, if TPP is subscribed for webhooks.</li><br/><li>The TPP makes the GET /v2/payments/{id} call and receives the payment with the status INITIATION_PENDING_REDIRECT_AUTH.</li></ol>