menu

Payment API

What's on this page

General / Idempotency

Idempotency

Idempotent requests are best used if there is no way to avoid duplicate requests. Time-outs are often the cause of retransmission and must be possible without side effects like processing the request twice.

Idempotency for Payment, Capture, Refund and Reversal requests can be enabled by adding the optional HTTP request header Idempotency-Reference. The header must contain a non-empty unique value of a maximum of 50 characters generated for each transaction.

We do not enforce a minimum length but we recommend a UUID generated for each new transaction and not for example a database id.

Data Fields

We treat a request as identical to another for idempotency when the exact same request header is used, and the following fields all match (also including empty or null values) for the selected operation:

Payment

  • transactionType
  • method
  • brand
  • amount
  • currency
  • issuer
  • storeInVault

Capture

  • reference
  • amount

Refund

  • reference
  • amount

Reversal

  • reference

Examples

Example payment request with idempotency header

curl --basic --user apikey: \
    -H "User-Agent: Shop123456" \
    -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" \
    -H "Content-Type: application/json" \
    --data '{  "amount" : 9.99,  "currency" : "eur",  "method" : "card",  "brand" : "visa",  "returnUrl" : "http://shop/return?order=123456",  "merchantOrderReference" : "123456",  "description" : "Order 123456",  "language" : "eng" }' \
    https://api.psp.ccv.eu/api/v1/payment

Example capture request with idempotency header

curl --basic --user apikey: \
    -H "User-Agent: Shop123456" \
    -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" \
    -H "Content-Type: application/json" \
    --data '{  "reference": "C1505181754007360.1", "amount" : 9.99, "description" : "Capture Order 123456"}' \
    https://api.psp.ccv.eu/api/v1/capture

Example refund request with idempotency header

curl --basic --user apikey: \
    -H "User-Agent: Shop123456" \
    -H "Idempotency-Reference: 1FAvu5eqNFwohXwPZLJajVecN5AIPaUl7qPFi4jFx4Hvt4SeUO" \
    -H "Content-Type: application/json" \
    --data '{  "reference": "C1505181754007360.1", "amount" : 9.99, "description" : "Refund Order 123456" }' \
    https://api.psp.ccv.eu/api/v1/refund

If we find an existing, identical request with the same idempotency reference for the same merchant account, we can guarantee the result will be the same as for the initial request for the same transaction and will not create a new one.

Any differences in the request using an existing idempotency reference will result in an input error.

Expiration

An idempotency reference will expire after 24 hours after which the same request with the same idempotency reference will result in a new transaction.

Data Selection

The only input that is used is the one provided in the very first idempotent request and further attempts using the same idempotency header value will never override or replace that input.