Refunds

Manually initiate a refund of a specific transaction.

POST /v2/refund

The amount refunded does not have to be the full amount of the original transaction, it can be less.

Sample

POST /v1/refund
{
  "TransactionReference": "BA0542FB-1C66-4868-B072-3B9474401578",
  "RefundAmountInCents": 133
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
sourceTransactionReference	string	No	A globally unique transaction reference (UUID) that identifies the original transaction that sourced the funds that you want to refund.
destinationTransactionReference	string	No	A globally unique transaction reference (UUID) that identifies the destination transaction that the refund request is associated with.
clientData	object?	No	A collection of public data that can be associated with the transaction.
refundAmountInCents	integer	No	The amount to refund. This value cannot be larger than the amount that was originally sourced by the transaction referenced by ZGA.Core.Models.Payments.RefundRequest.SourceTransactionReference.

{
  "sourceTransactionReference": "00000000-0000-0000-0000-000000000000",
  "destinationTransactionReference": "00000000-0000-0000-0000-000000000000",
  "clientData": {},
  "refundAmountInCents": 0
}

Responses

Status	Description
202	The request was successful but does not return any results.
400	The request failed validation, the error object will contain further information.
401	The authorization information provided is not valid, authentication is required to access this resource.
403	The authorization header does not contain the correct type or you do not have access to this resource.
404	The request was successful but does not return any results.
422	The request payload is invalid, the error object will contain further information.
429	Too many requests are being sent concurrently or rate limiting has taken effect.
500	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
success	boolean	No	Gets a value indicating whether the operation was successful.
result	object	No	A model to hold the details of a response to a refund request.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "refundStatusUrls": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Server-side/admin refund - initiate via the .NET admin SDK. Not available in the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/refund', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
using VantagePay.Models.Payments.Requests;

var refund = await adminClient.Payments.RefundAsync(new RefundRequest
{
    SourceTransactionReference = "e1d2c3b4-a5f6-4738-9a0b-1c2d3e4f5a6b",
    DestinationTransactionReference = "c7b8a9d0-1234-4567-89ab-cdef01234567",
    RefundAmountInCents = 5000,
});

---

Check the status of a refund.

GET /v2/refund/status/{refundReference}

Sample

POST /v1/refund/status/d66f8095-f355-4dfe-83ca-5d96e136f6f5

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
refundReference	path	Yes	A globally unique refund reference (UUID).

Responses

Status	Description
200	The request was successful but does not return any results.
400	The request failed validation, the error object will contain further information.
401	The authorization information provided is not valid, authentication is required to access this resource.
403	The authorization header does not contain the correct type or you do not have access to this resource.
404	The request was successful but does not return any results.
422	The request payload is invalid, the error object will contain further information.
429	Too many requests are being sent concurrently or rate limiting has taken effect.
500	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
success	boolean	No	Gets a value indicating whether the operation was successful.
result	object	No	A model to hold the details of the current status of a refund transaction.

{
  "success": true,
  "result": {
    "refundCompletedDate": "string",
    "createdDate": "string",
    "reference": "00000000-0000-0000-0000-000000000000",
    "shortReference": "string",
    "description": "string",
    "originalAmountInCents": 0,
    "amountAttemptedInCents": 0,
    "amountInCents": 0,
    "cashbackAmountInCents": 0,
    "fees": [],
    "data": [],
    "currency": "None",
    "status": 0,
    "category": 0,
    "summaryStatus": 0,
    "isComplete": true,
    "message": "string"
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Checks a refund status. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/refund/status/' + refundReference, {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
var status = await client.Payments.RefundStatusCheckAsync(Guid.Parse("d4c3b2a1-5678-4321-9876-fedcba098765"));

---

Get detailed refund information for generating receipts.

GET /v2/refund/receipt/{refundReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
refundReference	path	Yes	A globally unique refund reference (UUID).

Responses

Status	Description
200	The request was successful but does not return any results.
400	The request failed validation, the error object will contain further information.
401	The authorization information provided is not valid, authentication is required to access this resource.
403	The authorization header does not contain the correct type or you do not have access to this resource.
404	The request was successful but does not return any results.
422	The request payload is invalid, the error object will contain further information.
429	Too many requests are being sent concurrently or rate limiting has taken effect.
500	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
success	boolean	No	Gets a value indicating whether the operation was successful.
result	object	No	A model to hold the details of the current status of a refund transaction.

{
  "success": true,
  "result": {
    "yourReference": "string",
    "originalPaymentReceipt": {},
    "refundCompletedDate": "string",
    "createdDate": "string",
    "reference": "00000000-0000-0000-0000-000000000000",
    "shortReference": "string",
    "description": "string",
    "originalAmountInCents": 0,
    "amountAttemptedInCents": 0,
    "amountInCents": 0,
    "cashbackAmountInCents": 0,
    "fees": [],
    "data": [],
    "currency": "None",
    "status": 0,
    "category": 0,
    "summaryStatus": 0,
    "isComplete": true,
    "message": "string"
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Retrieves a refund receipt. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/refund/receipt/' + refundReference, {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
var receipt = await client.Payments.GetRefundReceiptAsync(Guid.Parse("d4c3b2a1-5678-4321-9876-fedcba098765"));

---

Generate a transaction for an external card refund.

POST /v2/refund/merchant/external-card

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
transactionDateUtc	string	No	The UTC date and time the terminal submitted the transaction.
timeZone	string?	No	The IANA or Windows time-zone identifier for the terminal's local time.
transactionBatchReference	string?	No	The payment engine transaction batch reference associated with this terminal transaction.
splitReference	string?	No	A shared split-payment reference that groups multiple batches contributing to the same consumer bill.
tipEmployeeReference	string?	No	The reference of the employee who should receive the tip, if applicable.
transactionReference	string?	No	The unique transaction reference assigned by the payment engine.
transactionNumber	string?	No	The transaction sequence number assigned by the terminal.
transactionType	string?	No	The transaction type descriptor as returned by the terminal (e.g. PURCHASE, REFUND).
merchantAccountNumber	string?	No	The merchant account number as returned by the terminal, with leading zeros stripped.
terminalNumber	string?	No	The terminal identifier, left-padded to 8 digits.
batchNumber	string?	No	The settlement batch number, left-padded to 3 digits.
customDescription	string?	No	An optional description that overrides the default transaction label, used for itemised receipts.
currency	one of 106 values (e.g. None, AFN, ALL, ...)	No	The currency in which the transaction was processed.
requestedAmountInCents	integer	No	The purchase amount in cents originally requested by the terminal.
approvedAmountInCents	integer	No	The purchase amount in cents approved by the acquiring host.
requestedCashbackAmountInCents	integer	No	The cashback amount in cents requested by the cardholder.
approvedCashbackAmountInCents	integer	No	The cashback amount in cents approved by the acquiring host.
requestedMerchantFeeInCents	integer	No	The merchant surcharge fee in cents requested.
approvedMerchantFeeInCents	integer	No	The merchant surcharge fee in cents approved by the acquiring host.
requestedTaxAmountInCents	integer	No	The tax amount in cents requested.
approvedTaxAmountInCents	integer	No	The tax amount in cents approved by the acquiring host.
requestedTipAmountInCents	integer	No	The tip amount in cents requested by the cardholder.
approvedTipAmountInCents	integer	No	The tip amount in cents approved by the acquiring host.
maskedCardNumber	string?	No	The masked PAN of the card used (e.g. 411111******1111).
expiryDate	string?	No	The card expiry date as returned by the terminal (format: MMYY or YYMM depending on scheme).
authCode	string?	No	The authorisation code returned by the issuer for an approved transaction.
authMode	string?	No	The authentication mode used (e.g. PIN, SIGNATURE, CONTACTLESS).
resultCode	string?	No	The ISO 8583 result code returned by the acquiring host (e.g. 00 for approved).
message	string?	No	A short human-readable outcome message.
detailedMessage	string?	No	A verbose description of the outcome, supplementing ZGA.Core.Models.Payments.ExternalCardTransactionData.Message.
hostResponse	string?	No	The raw response string returned by the acquiring host.
gatewayTransactionReference	string?	No	A unique transaction reference assigned by the payment gateway.
gatewayResponse	string?	No	The raw JSON or string response returned by the payment gateway.
avsResponse	string?	No	The Address Verification Service (AVS) response code returned by the issuer.
cvvResponse	string?	No	The Card Verification Value (CVV/CVC) check response code returned by the issuer.
issuerResponseCode	string?	No	The ISO 8583 response code returned by the card issuer.
globalUniqueIdentifier	string?	No	A globally unique identifier assigned to this transaction by the network or acquirer.
cardPresentFlag	string?	No	Flag indicating whether the card was physically present at the terminal (e.g. 1 = present, 0 = absent).
entryModeFlag	string?	No	The card-data entry mode flag (e.g. chip, swipe, contactless, manual).
pinStatusFlag	string?	No	Flag indicating the PIN entry status for this transaction.
apppn	string?	No	EMV Application Preferred Name (APPPN) from the chip.
aid	string?	No	EMV Application Identifier (AID) from the chip.
atc	string?	No	EMV Application Transaction Counter (ATC) from the chip.
ac	string?	No	EMV Application Cryptogram (AC) generated by the chip for this transaction.
tvr	string?	No	EMV Terminal Verification Results (TVR) - a bitmap of checks performed by the terminal.
tsi	string?	No	EMV Transaction Status Information (TSI) - indicates which functions were performed during processing.
cvm	string?	No	EMV Cardholder Verification Method (CVM) used (e.g. PIN, signature, no CVM).
ctq	string?	No	EMV Card Transaction Qualifiers (CTQ) - contactless transaction qualifier bitmap.
stan	string?	No	The Systems Trace Audit Number (STAN) assigned by the terminal for this transaction.
invoiceNumber	string?	No	The terminal-assigned invoice number for this transaction.
receiptNumber	string?	No	The receipt number printed on the customer copy.
nameOnCard	string?	No	The cardholder name as embossed or encoded on the card.
location	object	No	A geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
printLines	array<string>?	No	Free-text lines to be appended verbatim to the printed receipt.
lineItems	array<object>?	No	Itemised line items that make up this transaction (products or services purchased).
clientData	object?	No	A key-value map of arbitrary client data forwarded from the terminal to the payment engine.

{
  "transactionDateUtc": "string",
  "timeZone": "string",
  "transactionBatchReference": "00000000-0000-0000-0000-000000000000",
  "splitReference": "00000000-0000-0000-0000-000000000000",
  "tipEmployeeReference": "string",
  "transactionReference": "string",
  "transactionNumber": "string",
  "transactionType": "string",
  "merchantAccountNumber": "string",
  "terminalNumber": "string",
  "batchNumber": "string",
  "customDescription": "string",
  "currency": "None",
  "requestedAmountInCents": 0,
  "approvedAmountInCents": 0,
  "requestedCashbackAmountInCents": 0,
  "approvedCashbackAmountInCents": 0,
  "requestedMerchantFeeInCents": 0,
  "approvedMerchantFeeInCents": 0,
  "requestedTaxAmountInCents": 0,
  "approvedTaxAmountInCents": 0,
  "requestedTipAmountInCents": 0,
  "approvedTipAmountInCents": 0,
  "maskedCardNumber": "string",
  "expiryDate": "string",
  "authCode": "string",
  "authMode": "string",
  "resultCode": "string",
  "message": "string",
  "detailedMessage": "string",
  "hostResponse": "string",
  "gatewayTransactionReference": "string",
  "gatewayResponse": "string",
  "avsResponse": "string",
  "cvvResponse": "string",
  "issuerResponseCode": "string",
  "globalUniqueIdentifier": "string",
  "cardPresentFlag": "string",
  "entryModeFlag": "string",
  "pinStatusFlag": "string",
  "apppn": "string",
  "aid": "string",
  "atc": "string",
  "ac": "string",
  "tvr": "string",
  "tsi": "string",
  "cvm": "string",
  "ctq": "string",
  "stan": "string",
  "invoiceNumber": "string",
  "receiptNumber": "string",
  "nameOnCard": "string",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "printLines": [
    "string"
  ],
  "lineItems": [
    {}
  ],
  "clientData": {}
}

Responses

Status	Description
202	The refund request was submitted successfully.
400	The request failed validation, the error object will contain further information.
401	The authorization information provided is not valid, authentication is required to access this resource.
403	The authorization header does not contain the correct type or you do not have access to this resource.
404	The request was successful but does not return any results.
422	The request payload is invalid, the error object will contain further information.
429	Too many requests are being sent concurrently or rate limiting has taken effect.
500	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
success	boolean	No	Gets a value indicating whether the operation was successful.
result	object	No	A model to hold the details of a response to a refund request.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "refundStatusUrls": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// POS terminal refund integration - typically driven from the .NET SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/refund/merchant/external-card', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
using VantagePay.Models.Payments;

var refund = await client.Payments.RefundMerchantAsync(new ExternalCardTransactionData
{
    TransactionReference = "e1d2c3b4-a5f6-4738-9a0b-1c2d3e4f5a6b",
    TransactionBatchReference = Guid.Parse("c7b8a9d0-1234-4567-89ab-cdef01234567"),
    MerchantAccountNumber = "12345678",
    TerminalNumber = "00000042",
    RequestedAmountInCents = 5000,
});

---

Manually initiate a refund to a merchant.

POST /v2/refund/merchant

The amount refunded does not have to be the full amount of the original transaction, it can be less.

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
description	string?	No	An optional description explaining the reason for the refund.
transactionBatchReference	string?	No	The reference of the original transaction batch to refund.
refundCategory	0, 1, 2, 3, 4, 5, 6, 7, 8, 9	No	The transaction category that classifies this refund (e.g. ZGA.Core.Models.Payments.TransactionCategory.Merchant).
clientData	object?	No	A collection of public data that can be associated with the transaction.
refundAmountInCents	integer	No	The amount to refund in cents. When 0 the full original transaction amount is refunded.

{
  "description": "string",
  "transactionBatchReference": "00000000-0000-0000-0000-000000000000",
  "refundCategory": 0,
  "clientData": {},
  "refundAmountInCents": 0
}

Responses

Status	Description
202	The request was successful but does not return any results.
400	The request failed validation, the error object will contain further information.
401	The authorization information provided is not valid, authentication is required to access this resource.
403	The authorization header does not contain the correct type or you do not have access to this resource.
404	The request was successful but does not return any results.
422	The request payload is invalid, the error object will contain further information.
429	Too many requests are being sent concurrently or rate limiting has taken effect.
500	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
success	boolean	No	Gets a value indicating whether the operation was successful.
result	object	No	A model to hold the details of a response to a refund request.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "refundStatusUrls": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Merchant-initiated refund. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/refund/merchant', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
using VantagePay.Models.Payments;
using VantagePay.Models.Payments.Requests;

var refund = await client.Payments.RefundMerchantAsync(new MerchantRefundRequest
{
    TransactionBatchReference = "c7b8a9d0-1234-4567-89ab-cdef01234567",
    RefundCategory = TransactionCategory.Card,
    RefundAmountInCents = 5000,
});