Skip to main content

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 transaction can be 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 transaction falls through, your backend cancels it. The money is returned to the payer.
  • Either endpoint can instead split the money between the payee, the payer and you.
  • 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 'Idempotency-Key: 3f8a1c2e-7b4d-4e9a-8c1f-5d2b6a9e0c47'

The request has no body. To split the money instead, send a JSON body with payee, payer and tenant; see Split the money.

The transaction is marked as SUCCEEDED. The payee receives the money minus the transaction's fees, and the fees are paid out to you. Follow the payouts under payments.outbound in Transaction details, or as split payouts with GET /v2/transactions/{transactionId}/split-payouts.

Errors​

  • 400 Invalid action: the transaction has already succeeded, is cancelled or paid out, is suspended, has no payer, has a debt that hasn't been verified, has a split payout without a receiver, isn't fully paid, or has been paid more than it costs and the extra hasn't been paid out with a split payout.
  • 400 Amounts don't match: see Split the money.
  • 404 Not Found: the transaction 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 'Idempotency-Key: 9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d91'

The request has no body. To decide who receives what instead, use the payout endpoint; see Split the money.

The transaction is marked as CANCELLED, and everything the payer has paid is returned to them. No fees are kept. Split payouts you have set to be paid on the next payout are still paid, and the other split payouts are cancelled. If the payer hasn't paid yet, the transaction is simply cancelled.

Errors​

  • 400 Invalid action: the transaction has already succeeded, is already cancelled or paid out, is suspended, has no payer, or has a split payout set to NEXT_PAYOUT that is an unverified debt or has no receiver.
  • 404 Not Found: the transaction wasn't found.

Split the money​

The payout endpoint takes the optional fields payee, payer and tenant. Use them to decide who receives what when the transaction is closed, for example to keep a cancellation fee, or to pay the payee part of the amount and return the rest to the payer.

Split the money
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: 5c7e9a1b-3d5f-4a2c-9e8b-1f3d5a7c9e02' \
-d '{
"payee": { "amount": 800.00 },
"payer": { "amount": 150.00 },
"tenant": { "amount": 50.00 }
}'
  • payee.amount: The amount paid out to the payee.
  • payer.amount: The amount returned to the payer. If the payer paid with MobilePay, the money goes back through MobilePay.
  • tenant.amount: The amount paid out to your business account. It replaces the transaction's fees. Safepay's fee is taken from it. When the amount doesn't cover the fee, the rest is taken from your fees in later payouts before you are paid.

When you send any of the three fields, the rules are:

  • A field you leave out counts as 0.
  • Amounts can't be negative or have more than 2 decimals; otherwise the request fails with 400 Invalid amount.
  • The amounts must add up to the amount available for payout, so no money is left on the transaction. The available amount is everything paid into the transaction minus its split payouts that haven't been paid yet.
    • If payee is more than 0, every split payout counts.
    • If payee is 0, only the split payouts with timing NEXT_PAYOUT count. The others are cancelled, and their money is part of the available amount.
  • If payee is more than 0, the transaction is marked as SUCCEEDED. Otherwise it is marked as CANCELLED.
  • A transaction that is only partly paid can be closed this way, and money paid beyond the amount is shared like the rest.

If the amounts don't add up, the request fails with 400 Amounts don't match, and the error detail states the amount available.

The money is paid out in the next payout. Each share appears as a split payout under GET /v2/transactions/{transactionId}/split-payouts.

Once the transaction is closed, its split payouts can no longer be created or cancelled, and debt information can no longer be changed.

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​

eventNameSent when
transaction.succeededThe payout was released.
transaction.cancelledThe transaction was cancelled.

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