> ## Documentation Index > Fetch the complete documentation index at: https://docs.kashimi.tech/llms.txt > Use this file to discover all available pages before exploring further. # Initiate a payment **`provider.id` is not always required.** How you use the `provider` object depends on your integration: * **[Custom Bank Selection](/guides/provider-selection-flow)** — pass `provider.id` with the UUID of the bank the PSU selected in your UI. * **[Hosted Bank Selection](/guides/hosted-flow)** — omit `provider.id` and pass `provider.preferences` instead (e.g. `countryCodes`). Kashimi will display its own hosted bank selection screen. ## OpenAPI ````yaml POST /api/v1/ob/payments openapi: 3.0.0 info: title: Gatekeeper docs description: gatekeeper API version: 0.0.1 contact: {} servers: [] security: [] tags: [] externalDocs: description: JSON document url: /api/docs-json paths: /api/v1/ob/payments: post: tags: - OB summary: Create a payment operationId: PaymentsController_create_v1 parameters: - name: Accept-Language in: header description: >- Preferred initial UI language for payment initiation. The user will be able to change it later. Must be a two-letter ISO 639-1 language code (e.g., 'en' for English, 'fr' for French). Invalid values will be ignored. required: false schema: type: string - name: Authorization in: header description: Bearer token for authentication required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentInputDto' responses: '201': description: The payment object has been stored successfully content: application/json: schema: $ref: '#/components/schemas/CreatePaymentOutputDto' example: paymentId: 56caec01-85cc-4fc6-8080-cc0f7ed03a7e providerPaymentId: '123456789' redirectUrl: https://example.com/provider/specific/redirect/url createdAt: '2023-04-05T17:02:11.954Z' updatedAt: '2023-04-05T17:02:11.954Z' status: PENDING '400': description: The request is not formatted correctly content: application/json: example: statusCode: 400 title: Bad Request message: >- providerId should not be empty, providerId must be a UUID, paymentScheme should not be empty, paymentScheme must be one of the following values: SEPA, recipient must be a non-empty object, amount must not be less than 0.01, amount must be a number conforming to the specified constraints '401': description: >- Your access token was either not passed with the request, or it is invalid (e.g. expired or malformed). Make sure to pass the token in the Authorization header, and obtain a new one if it has expired. content: application/json: schema: $ref: '#/components/schemas/ErrorOutputDto' example: statusCode: 401 title: Unauthorized message: Unauthorized '403': description: You do not have the necessary permissions to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorOutputDto' example: statusCode: 403 title: Forbidden message: Access denied '404': description: Provider with the specified ID was not found. content: application/json: example: title: Not Found statusCode: 404 message: Provider with this ID was not found. '409': description: A payment with the specified endToEndId already exists. content: application/json: example: title: Conflict statusCode: 409 message: Payment with this end-to-end ID already exists. security: - bearer: [] x-codeSamples: - lang: cURL source: >- curl --location --request POST "https://api.kashimi.tech/api/v1/ob/payments" --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer YOUR_ACCESS_TOKEN" --data '{ "provider": { "id": "123e4567-e89b-12d3-a456-426614174000" }, "paymentScheme": { "name": "SEPA", "preferences": { "mode": "INSTANT" } }, "sender": { "account": { "number": { "type": "IBAN", "value": "DE89370400440532013000" }, "currency": "EUR" }, "address": { "country": "NL", "city": "Amsterdam", "streetName": "Damstraat", "buildingNumber": "1A", "postCode": "1012AB" } }, "recipient": { "account": { "number": { "type": "IBAN", "value": "DE89370400440532013000" } }, "name": "John Doe", "address": { "country": "NL", "city": "Amsterdam", "streetName": "Damstraat", "buildingNumber": "1A", "postCode": "1012AB" } }, "amount": 10, "currency": "EUR", "remittanceInformation": { "type": "UNSTRUCTURED", "value": "Invoice1234567890" }, "metadata": { "redirectUri": "https://example.com/redirect?paymentId=12345", "psuIpAddress": "84.240.80.120", "psuUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3", "endToEndId": "123456789123456789", "webhookUrl": "https://example.com/webhook" } }' components: schemas: CreatePaymentInputDto: type: object properties: provider: description: Data about the payment provider. allOf: - $ref: '#/components/schemas/PaymentProviderInputDto' paymentScheme: description: Payment scheme. example: name: SEPA allOf: - $ref: '#/components/schemas/PaymentPaymentSchemeInputDto' sender: description: Data about the party sending the payment. allOf: - $ref: '#/components/schemas/PaymentSenderInputDto' recipient: description: Data about the party receiving the payment. allOf: - $ref: '#/components/schemas/PaymentRecipientInputDto' amount: type: number description: The amount to be transferred. example: 10 currency: type: string description: The currency of the payment. example: EUR remittanceInformation: description: Unstructured or structured remittance information. allOf: - $ref: '#/components/schemas/PaymentRemittanceInformationInputDto' metadata: $ref: '#/components/schemas/PaymentMetadataInputDto' required: - paymentScheme - recipient - amount - currency - remittanceInformation - metadata CreatePaymentOutputDto: type: object properties: paymentId: type: string description: The Kashimi ID of the initiated payment example: 123e4567-e89b-12d3-a456-426614174000 providerPaymentId: type: string description: The provider ID of the initiated payment example: 123e4567-e89b-12d3-a456-426614174000 redirectUrl: type: string description: The URL to redirect the user to complete the payment example: https://your-website.com/authorize-payment createdAt: format: date-time type: string updatedAt: format: date-time type: string status: type: string description: The status of the initiated payment example: PENDING enum: - PENDING - COMPLETED - FAILED - UNKNOWN required: - paymentId - redirectUrl - createdAt - updatedAt - status ErrorOutputDto: type: object properties: title: type: string description: Name of the error statusCode: type: number description: HTTP status code message: type: string description: Error message required: - title - statusCode - message PaymentProviderInputDto: type: object properties: id: type: string description: >- The ID of the provider. Corresponds to the ID received from the Capabilities API. example: 123e4567-e89b-12d3-a456-426614174000 format: uuid preferences: description: Preferences for the payment providers. allOf: - $ref: '#/components/schemas/PaymentProviderPreferencesInputDto' PaymentPaymentSchemeInputDto: type: object properties: name: type: string description: Payment scheme. example: SEPA enum: - SEPA - DOMESTIC preferences: description: Preferences for the payment scheme. example: mode: INSTANT feePaidBy: SENDER allOf: - $ref: '#/components/schemas/PaymentPaymentSchemePreferencesInputDto' required: - name PaymentSenderInputDto: type: object properties: account: description: >- Sender's account data. If not provided, the PSU will be able to select the account during the payment initiation process. allOf: - $ref: '#/components/schemas/PaymentSenderAccountInputDto' address: description: Sender's address. allOf: - $ref: '#/components/schemas/PaymentAddressInputDto' credentials: description: Sender's online banking credentials. allOf: - $ref: '#/components/schemas/PaymentSenderCredentialsInputDto' PaymentRecipientInputDto: type: object properties: account: description: Recipient's account information. allOf: - $ref: '#/components/schemas/PaymentRecipientAccountInputDto' name: type: string description: Recipient's name. example: John Doe address: description: Recipient's address. allOf: - $ref: '#/components/schemas/PaymentAddressInputDto' required: - account - name - address PaymentRemittanceInformationInputDto: type: object properties: type: type: string description: Remittance information type. example: UNSTRUCTURED enum: - UNSTRUCTURED value: type: string description: >- Remittance information value. Maximum length depends on the payment scheme (140 characters for SEPA). Only alphanumeric characters and these special characters are allowed: / + - [space]. example: ABCD-EFGHI 12/34+567890 preferences: description: Preferences for remittance information. example: truncate: true allOf: - $ref: >- #/components/schemas/PaymentRemittanceInformationPreferencesInputDto required: - type - value PaymentMetadataInputDto: type: object properties: redirectUri: type: string description: >- The URI to which the PSU will be redirected once the payment flow is completed. example: https://example.com/redirect?paymentId=12345 psuIpAddress: type: string description: >- The IPv4 or IPv6 address of the PSU. Required by providers. IPv4 must be a full four-octet IP address, e.g. 84.240.80.120. IPv6 must be expanded to eight segments without the `::` shorthand. example: 84.240.80.120 psuUserAgent: type: string description: The user agent of the PSU. Required by providers. example: >- Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3 endToEndId: type: string description: The ID of the payment in your system. example: '123456789123456789' webhookUrl: type: string description: >- The URL where you want to receive a webhook when the payment status changes. Must be a valid HTTPS URL. example: https://example.com/webhook required: - redirectUri - psuIpAddress - psuUserAgent - endToEndId PaymentProviderPreferencesInputDto: type: object properties: countryCodes: description: >- Country codes that user will be able to select from when making a payment. example: list: - NL - DE default: NL allOf: - $ref: >- #/components/schemas/PaymentProviderPreferencesCountryCodesInputDto PaymentPaymentSchemePreferencesInputDto: type: object properties: mode: type: string description: >- Preferred urgency of the payment. This preference will be honored if the provider supports it, but it may be ignored - some providers pick the mode automatically. If INSTANT is preferred but isn't possible for the payment, STANDARD will be used as a fallback. example: INSTANT feePaidBy: type: string description: >- Preferred distribution of the transaction fees. Mostly irrelevant for SEPA Standard payments, but could be used for SEPA Instant in certain markets if charging (higher than standard) fees for instant payments is allowed there example: SENDER PaymentSenderAccountInputDto: type: object properties: number: description: >- Sender's account number data. If not provided, the PSU will either be able to select the account in the UI of the provider (if possible), or we will perform an AIS request to the provider and prompt the PSU to select an account. allOf: - $ref: '#/components/schemas/PaymentAccountNumberInputDto' currency: type: string description: >- Sender's account currency. If not provided, the PSU will either be able to select the account in the UI of the provider (if possible), or we will perform an AIS request to the provider and prompt the PSU to select an account. example: EUR enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SOS - SRD - SSP - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - UYI - UYU - UYW - UZS - VED - VES - VND - VUV - WST - XAF - XAG - XAU - XBA - XBB - XBC - XBD - XCD - XDR - XOF - XPD - XPF - XPT - XSU - XTS - XUA - XXX - YER - ZAR - ZMW - ZWG required: - number - currency PaymentAddressInputDto: type: object properties: country: type: string description: Country code of the address. enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - HR - CU - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FJ - FI - FR - GF - PF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - SS - ES - LK - SD - SR - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TV - UG - UA - AE - GB - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW example: NL city: type: string description: City of the address. example: Amsterdam streetName: type: string description: Street name of the address. example: Damstraat buildingNumber: type: string description: Building and apartment/office/suite number of the address. example: 1A postCode: type: string description: Postcode of the address. example: 1012AB required: - country - city - streetName - buildingNumber - postCode PaymentSenderCredentialsInputDto: type: object properties: id: type: string description: >- Sender's login id in the provider's system. If not provided, the PSU will be able to enter it during the payment process. example: '12345678' password: type: string description: >- Sender's password in the provider's system. If not provided, the PSU will be able to enter it during the payment process. example: password123 PaymentRecipientAccountInputDto: type: object properties: number: description: >- Sender's account number data. If not provided, the PSU will either be able to select the account in the UI of the provider (if possible), or we will perform an AIS request to the provider and prompt the PSU to select an account. allOf: - $ref: '#/components/schemas/PaymentAccountNumberInputDto' required: - number PaymentRemittanceInformationPreferencesInputDto: type: object properties: truncate: type: boolean description: >- If set to true, remittance information value will be truncated to fit the specified provider's requirements. If false or not provided, the value will be returned as is, and may cause errors if it exceeds provider limits. PaymentProviderPreferencesCountryCodesInputDto: type: object properties: list: type: string description: >- List of country codes that user will be able to select from when making a payment. enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - HR - CU - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FJ - FI - FR - GF - PF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - SS - ES - LK - SD - SR - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TV - UG - UA - AE - GB - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW example: - NL - DE default: type: string description: >- Default country code that user will be able to select from when making a payment. enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BA - BW - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - HR - CU - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FJ - FI - FR - GF - PF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GN - GW - GY - HT - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IL - IT - JM - JP - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MK - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - SS - ES - LK - SD - SR - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TV - UG - UA - AE - GB - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW example: NL PaymentAccountNumberInputDto: type: object properties: type: type: string description: Account number type. example: IBAN enum: - IBAN value: type: string description: Account number. example: DE89370400440532013000 required: - type - value ````