--- title: "Create a payment" method: POST path: "/v2/payments" tags: ["Payments"] --- # Create a payment `POST /v2/payments` ## Request - Base URL: `https://api.getpaid.io` - URL: `https://api.getpaid.io/v2/payments` - Auth: OAuth 2 - Client credentials - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payments:read_write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a payment initiated by the platform on behalf of a buyer. Related webhooks: - [`payment_captured`](#tag/Accept-payments-webhooks/operation/payment_captured): sent when the payment funds are captured and secured. - [`payment_failed`](#tag/Accept-payments-webhooks/operation/payment_failed): sent when a payment fails due to business (decline) or technical issues. ## Headers - `Getpaid-Idempotency-Key` string, required ## Request body - CreatePaymentRequest - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution. - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `currency` string, currency, required: The processing currency code according to the [ISO-4217 standard](https://en.wikipedia.org/wiki/ISO_4217) - `method` union: The payment method configuration for this payment. - CardPaymentMethodRequest: The payment method configuration for this payment. - `type` string, required: The payment method type. - `dynamic_descriptor` string, required: The card dynamic descriptor. It will be prefixed with `GPD*` when displayed on the buyer statement. You don't need to include the `GPD*` prefix in the value sent. - SddPaymentMethodRequest: The payment method configuration for this payment. - `type` string, required: The payment method type. - `remittance_info` string, required: The SEPA Direct Debit remittance information shown on the buyer statement. - `splits` SplitsRequest, required: The list of payment splits for the accounts involved in the funds flow. See [how splits work](/monetize/splits) for more information. - `type` 'per_transaction', required: The type of payment split. - `accounts` object[], required: The list of accounts involved in the payment that will receive the funds. - `type` 'platform' | 'seller' | 'other', required: The type of account. Exactly one of type `seller` is required and allowed per payment. - `id` string, id, required: The unique identifier of the account. - `split` union, required: The amount in the payment currency to be allocated to this account. - SplitFixedAmount: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - SplitPercentageAmountRequest: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `percentage` number, float, required: The percentage of the total amount to allocate to this account. - SplitRemainingAmountRequest: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `processing_fee` ProcessingFeeRequest: The processing fee covered by this account. If not specified, the account will not cover any processing fee, except when the payment has exactly one seller account and that seller is the authenticated platform account. In that platform-as-seller case, the API defaults the missing processing fee to 100%. The sum of all processing fees covered by all accounts must be exactly 100%. - `percentage` number, float, required: The percentage of the total processing fee that this account will cover. - `standing_instruction` SubsequentStandingInstructionRequest, required: Standing instruction for recurring payments. - `id` string, id, required: The unique identifier of the standing instruction. - `webhooks` PaymentWebhooksRequest: Configuration for webhooks to receive payment status updates. - `url` string, uri, required: The URL to which webhook events will be sent. ## Response `201` Created - CreatePaymentResponse - `id` string, id, required: The unique identifier of the payment. - `status` 'initiated' | 'action_required' | 'submitted' | 'authorized' | 'captured' | 'declined' | 'failed' | 'partially_refunded' | 'refunded', required: The status of the payment. See the [list, transitions, and description of each status](/payments/lifecycle) for more details. - `reason` PaymentReason: Reason of the status of the resource when it requires additional steps or is a failure state. - `code` string, required: Code to identify the cause of the status of the resource. - `description` string, required: Human-readable description of the reason for the status of the resource. - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution. - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator. - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator. - `statement_descriptor` string: The final statement descriptor shown on the buyer statement. This value is calculated per payment method: - **Cards**: `dynamic_descriptor` with the `GPD*` prefix. - **SEPA Direct Debit**: `remittance_info`. - `method` union, required: The payment method used. - CardPaymentMethodDetails - `type` 'card' | 'sepa_direct_debit', required: The type of payment method. - `display_hint` string, required: A hint of the payment method used. - `dynamic_descriptor` string, required: The card dynamic descriptor. It will be prefixed with `GPD*` when displayed on the buyer statement. You don't need to include the `GPD*` prefix in the value sent. - `card` object, required: The card details. - `scheme` 'visa' | 'mastercard', required: The card scheme. - `holder_name` string, required: The name of the cardholder as printed on the card. - `first_digits` string, required: The first four to six digits of the card number (BIN) that identify the issuing bank. - `last_digits` string, required: The last four digits of the card number. - `expiry_month` integer, required: The expiration month of the card. - `expiry_year` integer, required: The expiration year of the card. - `kind` 'credit' | 'debit': Kind of the payment card. - `segment` 'consumer' | 'corporate': Segment of the payment card. - SddPaymentMethodDetails - `type` 'card' | 'sepa_direct_debit', required: The type of payment method. - `display_hint` string, required: A hint of the payment method used. - `remittance_info` string, required: The SEPA Direct Debit remittance information shown on the buyer statement. - `bank_account` object, required: The bank account details. - `type` 'business' | 'consumer', required: The type of bank account. - `number` object, required: The bank account number details. - `type` 'iban', required: The type of bank account number. - `value` string, required: The bank account number value. - `splits` SplitsCalculatedAndCalculatingFees, required: The list of payment splits for the accounts involved in the funds flow. The final split amounts and processing fees have been calculated. - `type` 'per_transaction', required: The type of payment split. - `accounts` object[], required: The list of accounts involved in the payment that will receive the funds. - `type` 'platform' | 'seller' | 'other', required: The type of account. Exactly one of type `seller` is required and allowed per payment. - `id` string, id, required: The unique identifier of the account. - `version` string, version, required: A resource version. - `legal_name` string, required: The legal name of the account. - `split` union, required: The amount in the payment currency to be allocated to this account. - SplitFixedAmount: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - SplitPercentageAmountCalculated: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `percentage` number, float, required: The percentage of the total amount to allocate to this account. - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - SplitRemainingAmountCalculated: The amount in payment currency to be allocated to this account. The sum of all split amounts for all accounts must be exactly the total amount of the payment or use the `remaining` type for one of the accounts to allocate the remaining amount after all other splits have been calculated. - `type` 'fixed' | 'percentage' | 'remaining', required: The type of split amount. - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `processing_fee` ProcessingFeeCalculating, required: The processing fee covered by this account. If not specified, the account will not cover any processing fee, except when the payment has exactly one seller account and that seller is the authenticated platform account. In that platform-as-seller case, the API defaults the missing processing fee to 100%. The sum of all processing fees covered by all accounts must be exactly 100%. - `percentage` number, float, required: The percentage of the total processing fee that this account will cover. - `amount` integer: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `authentication` PaymentAuthentication: Information about the authentication performed for the payment if any. - `type` '3ds', required: The type of authentication performed for the payment. - `status` 'succeeded' | 'failed', required: The status of the authentication. - `succeeded`: the authentication was successful. - `failed`: the authentication failed. - `result` object: The 3DS authentication result. - `code` 'Y' | 'A' | 'N' | 'U' | 'R', required: The 3DS authentication result code. - `eci` '05' | '06' | '07' | '01' | '02' | '03', required: The Electronic Commerce Indicator (ECI) value for the authentication. - `totals` PaymentTotals, required: The payment totals summary to provide an overview of captured, refunded, refundable amounts and processing fees overall and per account associated with the payment. - `net` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `captured` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `refunded` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `refundable` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `processing_fees` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `accounts` object[], required: The breakdown of totals per account associated with the payment. - `type` 'seller' | 'platform', required: The type of account. - `id` string, id, required: The unique identifier of the account. - `version` string, version, required: A resource version. - `legal_name` string, required: The legal name of the account. - `net` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `captured` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `refunded` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `refundable` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). - `processing_fees` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR). ## Other responses - `400`: Bad Request - `401`: Unauthorized - `409`: Conflict - `422`: Invalid Parameters - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/458eae3d49ad?raw)