Skip to navigation
CollectPaymentsManage Payments

Refund a Payment

Initiates a refund against a completed payment, identified by its transactionId in the path. Omit refundValue for a full refund; supply it (amount in minor units) for a partial refund. When provided, the currency must match the original payment.

CrissCross executes refunds in one of two ways depending on what the originating provider supports: a provider refund through the provider’s native refund API, or a payout refund that returns the funds via a payout to the original destination. The latter is used when the originating provider does not expose a refund API — common for mobile money, and applicable to bank methods when full account details are held. Both paths are tracked against the original payment so the refundable balance is enforced uniformly. See the Refunds guide for details.

Eligibility (ownership, refundable state, refund window, and cumulative amount ≤ original) is validated when the refund is initiated. Call Get Payment Refundability beforehand to check whether a payment can be refunded and for how much.

Refunds are processed asynchronously. The response is a refund transaction in a non-terminal state; track completion by polling Retrieve Payment Status with the returned refund transactionId, or by subscribing to the refund.completed, refund.failed, refund.errored, and refund.cancelled webhook events.

Path parameters

transactionIdstringRequiredformat: "uuid"
Identifier of the original payment to refund. UUID v7.

Request

This endpoint expects an object.
refundValueobjectOptional
Refund amount in minor units. Omit for a full refund. When provided, the currency must match the original payment.
reasonstringOptional<=512 characters

Optional free-form reason for the refund, recorded for reporting and dispute defense.

Response

Refund accepted and created as an asynchronous refund transaction. Poll the returned transactionId for completion.

statusstring
Current transaction status.
transactionIdstring
Unique identifier for the transaction.
messagestring

Human-readable status message.

authStateobjectOptional

Detail for the transaction’s current state. When the transaction status is AUTH_REQUIRED, authMethodType says how the payer completes authentication, and a matching detail object (redirect, fields, ussd, bankTransfer) carries the specifics. Error states instead carry code, message, and the raw connectorFailureCode/connectorFailureMessage.

sessionIdstringOptionalformat: "uuid"
Session the transaction belongs to.
merchantReferencestringOptional
Merchant reference from the original session.
processorNamestringOptional

Name of the payment processor (if assigned).

processorReferencestringOptional

Processor reference (if available).

paymentMethodIdstringOptional

The payment method used, e.g. card or mobilemoney.

identifiersmap from strings to stringsOptional

Additional identifiers, usually sessionId and payerId.

paymentAttributesmap from strings to stringsOptional
Attributes associated with the payment.
batchPayoutIdstringOptional
Batch payout identifier, present when the transaction is part of a batch payout.
collectionobjectOptional

Amount the customer paid in the collection currency. Present only on transactions converted by Adaptive Currency Conversion — per-session rate or rate lock.

fxMidRatestringOptional

Spot mid-market rate at the time the FX quote was committed for this attempt (decimal string, 8 decimal places). Present only on FX-converted transactions.

fxAllInRatestringOptional

Mid rate + markup — the rate this attempt was actually converted at (decimal string, 8 decimal places). Present only on FX-converted transactions.

fxMarkupBpsintegerOptional>=0

Markup applied to this attempt in basis points (100 bps = 1%). Present only on FX-converted transactions.

fxFeeobjectOptional

Conversion fee, denominated in the collection currency. Present only on FX-converted transactions.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error