Sign in

v1

latestOpenAPI 3.0.02026-08-0696238481.7 KB
Payments

Refund a payment

Use this endpoint to refund an already captured payment session. Unlike voids, which are typically completed in minutes, refunds can take several days to be cleared by the card schemes.

post/payment-sessions/{paymentSessionId}/refunds

Path parameters

paymentSessionIdstring required

Payment Id to refund

Headers

Accountstring
Example:ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327

The linked accountId (use this when operating on payments related to a linked account)

Request body

amountinteger nullable

The amount to refund in minor digits. Can be omitted when not using partial captures or splits; the remaining amount will be refunded.

reasonstring nullable

The reason for the refund

refundPlatformFeeboolean nullable

A flag to indicate whether the platform fee should be refunded. If the payment amount is fully refunded, the platform fee will be too. If this is a partial refund then the platform fee will be refunded proportionally to the amount being refunded. By default this flag is false.

Example request

{
  "amount": 500,
  "reason": "Requested by the customer",
  "splits": {
    "items": [
      {
        "id": "sp_01FCTS1XMKH9FF43CAFA4CXT3P",
        "amount": 50,
        "fee": {
          "amount": 5
        }
      }
    ]
  },
  "captureTransaction": {
    "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P"
  }
}

Response

Refund request successfully accepted (Pending / Succeeded / Failed). If the status is Pending then the transaction will be completed asynchronously. Listen to the PaymentSession.refunded event on your webhook to be notified of the outcome.

idstring

The unique identifier for the transaction

paymentSessionIdstring

The unique paymentSessionId that this transaction relates to

amountinteger

The amount of the transaction in minor digits

currencystring

The ISO currency code

type'Authorization' | 'Void' | 'Capture' | 'Refund' | 'Chargeback' | 'ChargebackReversal'
status'Pending' | 'Failed' | 'Succeeded'
refundedAmountinteger nullable

The amount of the transaction that has been refunded, in minor digits.

platformFeeinteger nullable

Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits.

platformFeeRefundedAmountinteger nullable

Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits.

processingFeeinteger nullable

This field is now deprecated. Please use the /balance-transactions endpoint to see the fees paid on these transactions.

The processing fee that was taken for this transaction.

reasonstring nullable

An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded.

captureType'Final' | 'NotFinal' nullable

Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once Final, any remaining uncaptured amount will be marked as void within 7 days.

createdTimestampinteger

The epoch timestamp (seconds) when the transaction was initiated

lastUpdatedTimestampinteger

The epoch timestamp (seconds) when the transaction was last updated

Example response

{
  "id": "txn_01FCTS1XMKH9FF43CAFA4CXT3P_01FCTS1XMKH9FF43CAFA4CXT3P",
  "paymentSessionId": "ps_01FCTS1XMKH9FF43CAFA4CXT3P",
  "amount": 250,
  "currency": "GBP",
  "type": "Capture",
  "status": "Succeeded",
  "refundedAmount": 50,
  "platformFee": 50,
  "platformFeeRefundedAmount": 50,
  "processingFee": 7,
  "reason": "Requested by the customer",
  "captureType": "Final",
  "paymentMethod": {
    "type": "Card",
    "tokenizedDetails": {
      "id": "pmt_01G0EYVFR02KBBVE2YWQ8AKMGJ",
      "stored": true
    },
    "card": {
      "scheme": "Mastercard",
      "last4": "4242",
      "binDetails": {
        "issuer": "Ryft Bank Ltd",
        "issuerCountry": "GB",
        "fundingType": "Debit",
        "productType": "Consumer"
      }
    },
    "wallet": {
      "type": "ApplePay"
    },
    "billingAddress": {
      "firstName": "Nathan",
      "lastName": "Jones",
      "lineOne": "123 Test Street",
      "lineTwo": "456 Lane",
      "city": "Manchester",
      "country": "GB",
      "postalCode": "SP4 7DE",
      "region": "NY"
    },
    "checks": {
      "avsResponseCode": "Y",
      "cvvResponseCode": "M"
    }
  },
  "splitPaymentDetail": {
    "items": [
      {
        "id": "sp_01FCTS1XMKH9FF43CAFA4CXT3P",
        "accountId": "ac_b83f2653-06d7-44a9-a548-5825e8186004",
        "amount": 50,
        "fee": {
          "amount": 50
        },
        "description": "2 x The Selfish Gene",
        "metadata": {
          "productId": "123",
          "productDescription": "The Selfish Gene"
        }
      }
    ]
  },
  "processingDetail": {
    "issuerResponseCode": "00",
    "authorizationCode": "123456",
    "acquirerReferenceNumber": "12093810928309123"
  },
  "inPersonDetail": {
    "terminalDetail": {
      "id": "tml_01FCTS1XMKH9FF43CAFA4CXT3P"
    }
  },
  "createdTimestamp": 1470989538,
  "lastUpdatedTimestamp": 1470989538
}