Creating a refund

post https://swagger.io/transactions/1.0/transactions/{transactionReference}/refunds

With a valid object representation, this endpoint allows creating a new refund.

Path Params

transactionReference

string

required

length between 1 and 256

Path variable to uniquely identify the transaction.

Body Params

descriptionText

string

length between 0 and 160

Free format text description of the transaction provided by the client. This can be sent in a notification SMS and an account statement as a reference for the receiver.

requestDate

date-time

Creation date and time of the object as supplied by the client.

geoCode

string

length between 0 and 256

Shows the geographic location where the transaction was initiated.

requestingOrganisationTransactionReference

string

length between 0 and 256

Reference provided by the requesting organization that will be associated with the transaction.

amount

string

length between 1 and 23

Refund amount.

metadata

array of objects

length ≤ 20

A collection of key/value pairs. These can be used to populate additional object properties.

metadata

Headers

X-Date

date-time

Header parameter that informs the date and time when the message was originated. It is used for basic message integrity checks, to ensure the request is not stale. Note that the header was previously referenced as 'Date' in version 1.0 of the Mobile Money API.

X-CorrelationID

string

required

Header parameter to uniquely identify the request. Must be supplied as an UUID.

apikey

string

It is used to send the pre-shared client's API key to the server.

X-User-Bearer

string

required

It is used to send the user’s access token when OAuth 2.0/OIDC authorization framework is used for end-user authentication.

X-Callback-URL

uri

URL supplied by the client that will be used to return the callback in the form of an HTTP PUT.

Responses

Response body

object

requiredAction

object

Payment data used to complete the transaction at an external entity.

actionType

string

paymentcode redirecturl banktransfer bankconfirmation ticket awaitconfirmation qr qrimage confirmationserviceurl

data

expirationDate

date-time

status

string

active confirmed cancelled expired

relatedPaymentMethodData

object

amount

string

required

length between 1 and 23

Transaction amount.

currency

string

required

Currency of the transaction amount.

AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BOV BRL BSD BTN BWP BYN BZD CAD CDF CHE CHF CHW CLF CLP CNY COP COU CRC CUC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HRK HTG HUF IDR ILS INR IQD IRR ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRO MUR MVR MWK MXN MXV MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLL SOS SRD SSP STD SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD USN UYI UYU UZS VEF VND VUV WST XAF XAG XAU XBA XBB XBC XBD XCD XDR XOF XPD XPF XPT XSU XTS XUA XXX YER ZAR ZMW ZWL

type

string

required

Harmonised transaction type.

billpay deposit disbursement transfer merchantpay inttransfer adjustment reversal annulment withdrawal

subType

string

length between 0 and 256

A non-harmonised sub-classification of the transaction type. Values are not fixed and usage will vary depending on the provider.

descriptionText

string

length between 0 and 160

Free format text description of the transaction provided by the client. This can be sent in a notification SMS and an account statement as a reference for the receiver.

requestDate

date-time

Creation date and time of the object as supplied by the client.

requestingOrganisationTransactionReference

string

length between 0 and 256

Reference provided by the requesting organization that will be associated with the transaction.

oneTimeCode

string

length between 0 and 256

A one-time code that can either be supplied in the request or can be generated in the response, depending on the use case. An authorization code can be supplied in this property for requests that were pre-authorized."

geoCode

string

length between 0 and 256

Shows the geographic location where the transaction was initiated.

country

string

AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW

debitParty

required

creditParty

required

senderKyc

recipientKyc

reverts

string

This property shows the transaction that is subject to a reversal.

revertedBy

string

This property shows the transaction that reverts this transaction.

annuls

string

This property shows the transaction that is subject to an annulment.

annulledBy

string

This property shows the transaction that annuls this transaction.

disputes

string

This property shows the transaction that is subject to a dispute.

disputedBy

string

This property shows the transaction that disputes this transaction.

adjusts

string

This property shows the transaction that is subject to a adjustment.

adjustedBy

array of strings

This property shows the transactions that adjusted this transaction.

adjustedBy

refunds

string

This property shows the transaction that is subject to a refund.

refundedBy

array of strings

This property shows the transactions that refunded this transaction.

refundedBy

refundedAmount

string

length between 1 and 23

Total refunded amount of the transaction.

metadata

array of objects

length ≤ 20

A collection of key/value/creationDate objects. These can be used to populate additional properties.

metadata

object

key

string

required

length between 1 and 256

Identifies the type of additional property.

value

string

required

length between 1 and 256

Identifies the value of the additional property.

creationDate

date-time

required

Date and time when the metadata entry was created.

transactionStatus

string

required

Indicates the status of the transaction as stored by the API provider."

finished processing error conciliate reverted reserved cancelled pending waiting annulled

transactionSubStatus

string

Indicates the internal status of the transaction as stored by the API provider."

initial finished error conciliate reverted reserved cancelled secondStepInitial pending pendingExpired ongoingExpired pendingRejected pendingCancelled conciliateReversal waiting reverting processingPayment conciliating pendingSettlement processingSettlement settled processingAnnulment annulled

creationDate

date-time

Date and time when the object was created by the API provider.

modificationDate

date-time

Date and time when the object was modified by the API provider.

transactionReference

string

required

length between 1 and 256

Unique reference for the transaction.

transactionReceipt

string

length between 0 and 256

Transaction receipt number as notified to the parties. This may differ from the transaction reference.

fees

object

debitPartyEarnedCommission

string

required

length between 1 and 23

debitPartyPaidCommission

string

required

length between 1 and 23

creditPartyEarnedCommission

string

required

length between 1 and 23

creditPartyPaidCommission

string

required

length between 1 and 23

debitPartyNetCommission

string

required

length between 1 and 23

creditPartyNetCommission

string

required

length between 1 and 23

error

object

errorCategory

string

required

Category that groups the error.

businessRule validation authorisation identification internal serviceUnavailable

errorCode

string

required

Harmonised error code identifying the error reason.

errordescription

string

length between 0 and 256

Consists of a text error."

errorDateTime

date-time

Timestamp of the error.

errorParameters

array of objects

length ≤ 20

A collection of key/value pairs. These can be used to populate additional object properties.

errorParameters

object

key

string

required

length between 1 and 256

Identifies the type of additional property.

value

string

required

length between 1 and 256

Identifies the value of the additional property.

object

debitPartyRate

object

creditPartyRate

object

confirmed

boolean

Defines if its a pending transaction or not.

paid

boolean

Defines if its a paid transaction or not.

paidDate

date-time

Date in which the transaction was paid.

confirmationExpirationDate

date-time

Expiration date and time of the pending transaction.

conciliationOptions

array of strings

conciliationOptions

expectedSettlementDate

date-time

Expected Settlement Date.

settlementDate

date-time

Settlement Date.

instructions

string

Hosted Checkout URL.

Headers

object

X-Date

date-time

Date and time when the response message was sent.

Callbacks

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request POST \
2
     --url https://swagger.io/transactions/1.0/transactions//refunds \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Represents a transaction refund response.

400Represents an error caused by a business rule violation.

401Represents an error caused by an authorization failure.

404Represents an error caused by a failure to identify the target resource.

500Represents an error caused by a general server-side issue.

503Represents an error caused by system unavailability.