v1

latestOpenAPI 3.1.02026-07-24130244.8 KB

Create payment

post/payments

Headers

Content-Typestring required

Always send this header as application/json.

Hoststring required

The host declared in the signature.

Datestring required

The date declared in the signature.

Digeststring required

The digest declared in the signature.

Authorizationstring required

The request signature.

Idempotency-Keystring

The idempotent request key. You can read more here.

x-satispay-deviceinfostring

The device information (e.g., hostname).

The device type.

x-satispay-osstring

The Operating System name (e.g., Windows).

x-satispay-osvstring

The Operating System version (e.g., 10).

x-satispay-apphstring

The software house name (e.g., Satispay).

x-satispay-appnstring

The software name (e.g., My awesome app).

x-satispay-appvstring

The software version (e.g., v2.0.0).

x-satispay-tracking-codestring

The tracking code used by Satispay commercial partners. Use this code only if explicitly required by Satispay.

Request body

The payment flow that you want to use. MATCH_CODE DOC This flow can be used generically for one-off payments. HOTP_AUTH DOC This flow can be used to perform one-off payments via HOTP tokens. To use this flow you must also include the token parameter. MATCH_USER DOC This flow can be used for one-off payments on a specific user. To use this flow you must also include the consumer_uid parameter. FUND_LOCK DOC This flow can be used for funds lock payments. PRE_AUTHORIZED DOC This flow can be used for automatic payments. To use this flow you must also include the token parameter. PRE_AUTHORIZED_FUND_LOCK DOC This flow can be used for automatic funds lock payments. To use this flow you must also include the token parameter. REFUND This flow can be used for refunds on a specific payment. To use this flow you must also include the parent_payment_uid and the amount_unit.

amount_unitinteger required

The payment amount in cents. For example, to represent the amount €12.40, you should multiply it by 100, resulting in 1240 cents.

currencystring required

The payment currency. Currently EUR is the only currency supported.

pre_authorized_payments_tokenstring

The payment automatic payment token id. This has been replaced with the new token parameter.

tokenstring

The token required to charge the consumer wallet. It can be an automatic payment or HOTP token. Required with HOTP_AUTH, PRE_AUTHORIZED and PRE_AUTHORIZED_FUND_LOCK flows only.

consumer_uidstring

The unique id of the consumer required for payment acceptance. To obtain the customer id, please use the Get Consumer API. Required with MATCH_USER flow only. This parameter is deprecated; we suggest avoiding the MATCH_USER UX unless absolutely necessary.

parent_payment_uidstring

The id of the payment that you want to refund. Required with REFUND flow only.

external_codestring

The external order id or payment identifier. We highly recommend to use this field by populating it with your internal order id. This string will be included in your reports for reconciliation and shown to the Satispay consumer in-app. This field has a maximum length of 50 characters, including spaces.

callback_urlstring

The URL to be triggered via an HTTP GET request when there is a change in payment status. When the given callback_url is invoked, a GET request for payment details can be made to retrieve the updated payment status. Please note that {uuid} will be replaced with the generated payment id. e.g. https://example.com/satispay-callback?payment_id={uuid} You can read more here.

redirect_urlstring

This field specifies the URL where the user will be redirected after the payment flow from the Satispay app is completed. For instance, you can set this URL to ensure users are redirected to that specific page upon successful payment completion. e.g. https://example.com/payment-redirect?order_id=your_order_id Please note that this field doesn't support any placeholder.

expiration_datestring

The UTC payment expiration datetime. The format should be ISO 8601 like this yyyy-MM-dd'T'HH:mm:ss.SSSZ. By default: MATCH_CODE and MATCH_USER payments are valid for 2 hours. FUND_LOCK payments are valid for 10 days. PRE_AUTHORIZED_FUND_LOCK payments are valid for 5 days. This timeframe is calculated from the moment of creation. This parameter cannot be used with PRE_AUTHORIZED, HOTP_AUTH and REFUND flows.

Response

idstring

The unique payment id. This can be used for every eventual subsequent operations on the payment, including refunds.

code_identifierstring

The Satispay code identifier. This string can be encoded in a QR code that can be scanned by the user. This property is only available in MATCH_CODE flow payments.

typestring

The current payment type. TO_BUSINESS This type is used for payments from a consumer to a merchant. REFUND_TO_BUSINESS This type is used for payments from a merchant to a consumer (e.g. refunds).

amount_unitinteger

The payment amount in cents. For example, the amount €12.40 is being represented as 1240 cents.

currency'EUR'

The payment currency.

statusstring

The current payment status. PENDING The payment is created and awaits user interaction, such as scanning the QR code. AUTHORIZED - for FUND_LOCK and PRE_AUTHORIZED_FUND_LOCK flows only. The payment has been authorized by the user and is ready to be confirmed by the merchant with the Update payment API. ACCEPTED The payment has been accepted and succesfully executed.

expiredboolean

The current payment expiration status. It becomes true once it reaches the expiration_date without being accepted or canceled.

metadataobject

The additional metadata for the payment.

insert_datestring

The UTC payment creation datetime.

expire_datestring

The UTC payment expiration datetime. This property can be ignored when using PRE_AUTHORIZED or HOTP_AUTH flows.

descriptionstring

The external_code set during the payment creation request. Please use the external_code field instead.

flowstring

external_codestring

The external_code set during the creation request.

redirect_urlstring

The URL where the user will be redirected after the payment flow from the Satispay app is completed. This property is available only when the payment uses the MATCH_CODE, MATCH_USER or FUND_LOCK flow.