Create Payment Consent
POST {{base_url}}/banking/v2/pay/domestic/consents
Create Payment Consent
Before initiating a payment, a payment request must be created and presented to the user for their consent.
Payment request must include the bank details of the payee and the details of the payment (amount, currency and payment type).
Calling this endpoint will generate a payment link (authUrl) that can be sent to the payer. The payer will have to authorise the payment by authenticating with their bank before it can be completed.
On successful authentication, a code, id_token, and state will be returned along with the bankId.
Attributes
| Field | Type | Description |
|---|---|---|
| bankId | integer | Unique identifier for the bank |
| redirect | string (link) | URL to redirect to after the bank account is added |
| creditor | JSON object | Creditor information |
| creditor -> schemeName | string | IBAN or Account and sort code |
| creditor -> identification | string | Creditor's account details |
| creditor -> name | string | Creditor name |
| currency | string | Account currency |
| amount | integer | Payment amount |
| reference | string | Transaction reference |
| type | string | Payment type {DOMESTIC} |
| code | string | Temporary code to be exchanged for access token with the bank |
| id_token | string | Base64 encoded JSON for verifying state and token’s validity |
| state | string | Base64 encoded JSON containing information about the original request to persist the state throughout the user journey |
| state->nonce | string | String value used to associate a client session with an ID Token, and to mitigate replay attacks (for internal use) |
| state->reRed | string | Redirect URL |
| state->accReq | string | tomato pay consentId |
| state->bId | integer | bankId (Unique identifier for the bank) |
| state->consentId | string | bank consentId |
Response
| Field | Type | Description |
|---|---|---|
| signInUrl | string | Sign in URL for the requested bank |
| consentId | string | Unique ID for the consent |
| status | string | |
| bankId | integer | Unique identifier for the bank |
Error Messages
| Condition | Response Status | Response Body |
|---|---|---|
| Invalid bankId | 403 Forbidden | |
| No request body | 400 Bad Request | {error: "Missing/Invalid redirect”} |
| Missing/Invalid redirect | 400 Bad Request | {error: "Missing/Invalid redirect”} |
| No currency in the request body | 400 Bad Request | {error: Missing/invalid currency} |
| No amount in the request body | 400 Bad Request | {error: Missing/invalid amount} |
| Reference greater than 35 characters in the request body | 400 Bad Request | {error: The reference field has a maximum of 35 chars} |
| Invalid type | 400 Bad Request | {error: "Missing/Invalid type. Must be DOMESTIC |
| No creditor in the request body | 400 Bad Request | {error: Missing/Invalid creditor.name} |
| Invalid schemeName in request body | 400 Bad Request | error: Missing/Invalid creditor.schemeName |
| Invalid identification in request body | 400 Bad Request | error: Missing/Invalid creditor.identification |
| Bank error | 502 Bad Gateway | {error: “Bank error”} |
| Server error | 500 Internal server error |
Request Body
{"bankId"=>"6", "redirect"=>"redirect_url", "creditor"=>{"schemeName"=>"UK.OBIE.SortCodeAccountNumber", "identification"=>"Identification", "name"=>"Account name"}, "reference"=>"Reference", "amount"=>"1.00", "currency"=>"GBP", "type"=>"DOMESTIC"}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string | ||
X-Api-Key | string | ||
X-Partner-Id | string | ||
Authorization | string | ||
X-Company-Id | string |
RESPONSES
status: Created
{"signInUrl":"www.bankauthURL","consentId":"consentId1234","status":"AWAITINGAUTHORISATION","bankId":6}