Complete transaction

This page details how a transaction is closed once the payer has paid into escrow. It assumes that you have created a transaction using the Checkout flow.

How it works

• The payer has paid, and the transaction has the status INPROGRESS.
• When the trade is completed, for example when the payer has received the item, your backend releases the payout. The money is paid out to the payee.
• If the trade falls through, your backend cancels the transaction. The money is returned to the payer.
• If you have subscribed to webhooks, your backend receives a transaction.succeeded or transaction.cancelled webhook.

A transaction that has succeeded can't be cancelled, and a cancelled transaction can't be paid out.

Both endpoints support the Idempotency-Key header. Always send one, so a retried request can't release or cancel twice. See Idempotency.

Release payout

Release payout

curl https://sandbox-api.safepaynordic.dk/v2/transactions/{transactionId}/payout \
  -X POST \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3f8a1c2e-7b4d-4e9a-8c1f-5d2b6a9e0c47' \
  -d '{
        "safepayAccountId": "003dc3d2-dc30-4b37-a573-f664a03f5154"
      }'

• safepayAccountId: Required. The user on whose behalf the payout is released, usually the payer. Must be connected to you.

The transaction is marked as SUCCEEDED and the payout to the payee is scheduled. Follow the payout under payments.outbound in Transaction details.

Errors

• 400 Invalid action: the transaction has already succeeded, is cancelled, or has no payer.
• 404 Not Found: the transaction or the safepayAccountId wasn't found.

Cancel transaction

Cancel transaction

curl https://sandbox-api.safepaynordic.dk/v2/transactions/{transactionId}/cancel \
  -X POST \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d91' \
  -d '{
        "safepayAccountId": "003dc3d2-dc30-4b37-a573-f664a03f5154",
        "reason": "The item was not as described"
      }'

• safepayAccountId: Required. The user on whose behalf the transaction is cancelled. Must be connected to you.
• reason: Required when the payer has paid. Why the transaction is cancelled.

The transaction is marked as CANCELLED and any payments are returned to the payer. If the payer hasn't paid yet, the transaction is simply cancelled.

Errors

• 400 Invalid action: the transaction has already succeeded or is already cancelled.
• 400 Bad Request: no reason was supplied for a transaction that has been paid.
• 404 Not Found: the transaction or the safepayAccountId wasn't found.

Delete transaction

A transaction the payer hasn't paid can also be deleted instead of cancelled, for example if it was created by mistake.

Delete transaction

curl https://sandbox-api.safepaynordic.dk/v2/transactions/{transactionId}/delete \
  -X POST \
  -H 'Authorization: Bearer {API_TOKEN}'

The request fails with 400 Bad Request if the transaction has authorized payments; cancel it instead. An unknown transactionId returns 404 Not Found.

Webhooks

eventName	Sent when
transaction.succeeded	The payout was released.
transaction.cancelled	The transaction was cancelled.

The webhooks have the same format as described in Checkout. No webhook is sent when a transaction is deleted.