API Documentation

Create payment

post
https://authservices.satispay.com/g_business/v1/payments

The following guide explains how to create and accept payments using Satispay Meal Vouchers.

In this page, you can find the specific request parameters that you can use for Meal Voucher payments.
To read the generic API specification please refer to this page.

Payment creation

If your shop has Meal Vouchers enabled, Meal Vouchers will be used based on the user's Meal Voucher availability.
These Meal Vouchers will be applied if the user sets the Meal Vouchers wallet as their primary wallet.

It is not possible to have a combination of Meal Vouchers and Fringe Benefits in the same payment, since these two payment methods are mutually exclusive; however, it is possible to include Satispay Meal Vouchers and e-money in the same payment.

Furthermore, it is possible to define the maximum number and the maximum amount of Meal Vouchers that can be used for a single payment.
If you do not set these parameters, and if your shop has Meal Vouchers enabled, Meal Vouchers will be automatically used based on the consumer's Meal Vouchers availability, with a default limit of 8 Meal Vouchers per payment.

Partial payments

When integrating Satispay Meal Vouchers in cash registers / tills is required to implement what we call partial payment.
This flow enables merchants to accept payments from consumers who only have Meal Vouchers available in the Satispay App.

Refunds

Refunds are only possible on the same day of payment creation and for the total amount of the payment.
Partial refunds in payments with Meal Vouchers are not available.

To perform refunds you need to create a new payment with the REFUND flow.
You will need to send the parent_payment_uid with the payment id that you want to refund and the total amount_unit of the parent payment.

We suggest you to fill the external_code with your internal order id, in order to better reconcile refunds in your payment reports.
This field will also be shown to the user via the Satispay app.

🚧

Partial refund

Meal Voucher payments cannot be partially refunded.
You must set amount_unit with the total amount of the payment.

REQUEST

Body Params
string
enum
required

The payment flows that you can use with Meal Vouchers are:

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.

REFUND DOC
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.

Allowed:
integer
required

The payment amount in cents.

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

string
required
Defaults to EUR

The payment currency.

Currently EUR is the only currency supported.

payment_method_options
object
payment_options
object
string

The token required to charge the consumer wallet.
It can be an HOTP token.

Required with HOTP_AUTH flow only.

string
deprecated

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.

string

The id of the payment that you want to refund.

Required with REFUND flow only.

string

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.

string

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.

string

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.

metadata
object

The additional metadata for the payment.

This field supports up to 20 key-value pairs, with keys limited to 45 characters and values limited to 500 characters each.

string

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.

This parameter cannot be used with HOTP_AUTH and REFUND flows.

Headers
string
required

Always send this header as application/json.

string
required

The host declared in the signature.

string
required

The date declared in the signature.

string
required

The digest declared in the signature.

string
required

The request signature.

string

The idempotent request key.

You can read more here.

string

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

string
enum

The device type.

Allowed:
string

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

string

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

string

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

string

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

string

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

string

The tracking code used by Satispay commercial partners.

Use this code only if explicitly required by Satispay.

Responses

Updated 10 months ago

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 10 months ago