Swagger
The swagger (Open API) definition of the interface specification can be found here, as well as below.
Many tools are available for processing swagger files, and using a code generation tool to create a boilerplate client or server can be an excellent starting point for development. We highly recommend looking at swagger-codegen for a generator in your preferred language when starting out.
Swagger definition
---
swagger: "2.0"
info:
description: "The Electrum SUV Service describes an
interface\
\ for
single use voucher transactions."
version: "1.13.0"
title: "SUV Service Interface"
contact:
name: "Electrum Support"
url: "http://io.electrum"
email: "support@electrum.co.za"
license:
name: "Apache 2.0"
url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "sandbox.electrum.io"
basePath: "/suv/v1"
schemes:
- "https"
paths:
/redemptions:
post:
summary: "Redeems a voucher."
description: "This operation is performed when a voucher is used as a form of\
\ tender. When used as a form of tender the consumer redeems the requestAmount\
\ against the voucher. The voucher vendor is responsible for authorizing the\
\ redemption. Once redeemed, the voucher may not be used as a form of tender\
\ again."
operationId: "redeemVoucher"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A redemption request."
required: true
schema:
$ref: "#/definitions/RedemptionRequest"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/RedemptionResponse"
201:
description: "Created"
schema:
$ref: "#/definitions/RedemptionResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/redemptions/confirmations:
post:
summary: "Confirm a voucher redemption request that completed successfully."
description: "Once a redemptionRequest has completed successfully there is typically\
\ no need to notify the voucher vendor of the successful completion of the\
\ sale. However, this API recognises that client implementations may be very\
\ familiar with dual message APIs and this confirmation operation is provided\
\ to achieve consistency across the API with respect to single vs dual message\
\ operations. By performing this operation the client indicates that no subsequent\
\ reversal of the redemption will be performed. Note though that the successful\
\ completion of the confirmRedemption operation does not guarantee that the\
\ voucher will not be refunded in future."
operationId: "confirmRedeem"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher redemption confirmation."
required: true
schema:
$ref: "#/definitions/BasicAdvice"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/BasicAdvice"
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdvice"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/redemptions/reversals:
post:
summary: "Reverse a voucher redemption request."
description: "If a voucherRedemption request fails with one of the 5xx HTTP\
\ statuses code, or no response was received within the timeout period, it\
\ must be reversed to ensure the vendor does not consider the voucher to be\
\ in redeemed state. reverseRedemption must be repeated until a final HTTP\
\ status code is received (i.e. not 5xx). reverseRedemption may be called\
\ repeatedly on the same voucher resource without negative effect. If a voucher\
\ redemption is reversed there is no need to perform a refund against the\
\ voucher."
operationId: "reverseRedeem"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher redemption reversal."
required: true
schema:
$ref: "#/definitions/BasicReversal"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/BasicReversal"
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicReversal"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/redemptions/{requestId}:
get:
summary: "Looks up and returns the outcome of a prior voucher redemption."
description: "This operation may be used to obtain the result of a previous\
\ redemption request. It returns one of five classes of response: the original\
\ approved response,the original error response, a HTTP status code of 102\
\ if the original request is still being processed and no response is available\
\ yet, a HTTP status code of 403 if the client did not submit the original\
\ request and is therefore not permitted to obtain the response, a HTTP status\
\ code of 404 if the original request was not received."
operationId: "lookupRedemption"
produces:
- "application/json"
parameters:
- name: "requestId"
in: "path"
description: "The randomly generated UUID of this request."
required: true
type: "string"
responses:
102:
description: "Processing"
200:
description: "OK"
schema:
$ref: "#/definitions/RedemptionResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
403:
description: "Forbidden"
404:
description: "Not Found"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/refunds:
post:
summary: "Refunds a voucher."
description: "This operation is performed when a voucher was previously successfully\
\ redeemed. Should a consumer request a refund from the merchant, the merchant\
\ may use the refundVoucher operation to request the voucher be placed back\
\ into an unredeemed state. The voucher vendor is responsible for authorizing\
\ the refund. Once refunded, the voucher may be used as a form of tender again\
\ if allowed by the voucher vendor."
operationId: "refundVoucher"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A refund request."
required: true
schema:
$ref: "#/definitions/RefundRequest"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/RefundResponse"
201:
description: "Created"
schema:
$ref: "#/definitions/RefundResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/refunds/confirmations:
post:
summary: "Confirm a voucher refund request that completed successfully."
description: "Once a refundRequest has completed successfully there is typically\
\ no need to notify the voucher vendor of the successful completion of the\
\ refund. However, this API recognises that client implementations may be\
\ very familiar with dual message APIs and this confirmation operation is\
\ provided to achieve consistency across the API with respect to single vs\
\ dual message operations. However, by performing this operation the client\
\ indicates that no subsequent reversal of the refund will be performed."
operationId: "confirmRefund"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher refund confirmation."
required: true
schema:
$ref: "#/definitions/BasicAdvice"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/BasicAdvice"
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdvice"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/refunds/reversals:
post:
summary: "Reverse a voucher refund request."
description: "If a voucherRefund request fails with one of the 5xx HTTP statuses\
\ code, or no response was received within the timeout period, it must be\
\ reversed to ensure the vendor does not consider the voucher to be in a refunded\
\ state. reverseRefund must be repeated until a final HTTP status code is\
\ received (i.e. not 5xx). reverseRefund may be called repeatedly on the same\
\ voucher resource without negative effect."
operationId: "reverseRefund"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher refund reversal."
required: true
schema:
$ref: "#/definitions/BasicReversal"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/BasicReversal"
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicReversal"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/vouchers:
get:
summary: "Lookup a voucher using the voucher code."
description: "This operation is used to verify the validity of a voucher and\
\ possibly establish the value of a previously issued voucher (if supported\
\ by the server). This operation has no financial impact and is informative\
\ only."
operationId: "lookupVoucher"
produces:
- "application/json"
parameters:
- name: "voucherCode"
in: "query"
description: "The voucher code to be looked up."
required: false
type: "string"
- name: "provisionRequestId"
in: "query"
description: "The provision request id that was part of the original provision\
\ request to obtain a voucher."
required: false
type: "string"
- name: "receiverInstId"
in: "query"
description: "The institution which issued the voucher. This assists to direct\
\ the voucher lookup request if the destination cannot be determined from\
\ the voucher code alone."
required: false
type: "string"
- name: "settlementEntityInstId"
in: "query"
description: "The institution via which the lookup should be processed. This\
\ serves to better direct the lookup request in the case that multiple upstream\
\ parties are able to process the request."
required: false
type: "string"
- name: "voucherSerialNumber"
in: "query"
description: "The serial number of the voucher being looked up."
required: false
type: "string"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/VoucherLookupResponse"
202:
description: "Accepted"
schema:
$ref: "#/definitions/VoucherLookupResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
post:
summary: "Request a voucher be provisioned."
description: "Requests a voucher from the voucher vendor."
operationId: "provisionVoucher"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A provision request."
required: true
schema:
$ref: "#/definitions/ProvisionRequest"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/ProvisionResponse"
201:
description: "Created"
schema:
$ref: "#/definitions/ProvisionResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/vouchers/confirmations:
post:
summary: "Confirm a voucher provision request that completed successfully."
description: "Once a consumer has paid for a voucher and received the voucher\
\ from the merchant the merchant must notify the vendor that the voucher may\
\ be redeemed at some point in the future as per the voucher vendor's instructions.\
\ confirmVoucher must be repeated until a final HTTP status code is received\
\ (i.e. not HTTP 5xx). confirmVoucher may be called repeatedly on the same\
\ voucher resource without negative effect."
operationId: "confirmVoucher"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher provision confirmation."
required: true
schema:
$ref: "#/definitions/TenderAdvice"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/TenderAdvice"
202:
description: "Accepted"
schema:
$ref: "#/definitions/TenderAdvice"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
/vouchers/reversals:
post:
summary: "Reverse a voucher provision request that failed or timed out."
description: "If a voucherProvision request fails with one of the 5xx HTTP statuses\
\ code, or no response was received within the timeout period, it must be\
\ reversed to ensure the vendor knows to never expect further messages pertaining\
\ to the voucher. reverseVoucher must be repeated until a final HTTP status\
\ code is received (i.e. not 5xx). reverseVoucher may be called repeatedly\
\ on the same voucher resource without negative effect."
operationId: "reverseVoucher"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A voucher provision reversal."
required: true
schema:
$ref: "#/definitions/BasicReversal"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/BasicReversal"
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicReversal"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
404:
description: "Not Found"
schema:
$ref: "#/definitions/ErrorDetail"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ErrorDetail"
503:
description: "Service Unavailable"
schema:
$ref: "#/definitions/ErrorDetail"
504:
description: "Gateway Timeout"
schema:
$ref: "#/definitions/ErrorDetail"
security:
- httpBasic: []
securityDefinitions:
httpBasic:
description: "All requests require HTTP basic
authentication,
\
\ where user name equals the value used
\
\ in
Client.Institution.id
and\
\ password has been agreed
with Electrum."
type: "basic"
definitions:
Amounts:
type: "object"
properties:
requestAmount:
description: "The transaction amount requested by the customer to be authorised\
\ or approved. This is the total amount the customer wishes to pay for a\
\ service or virtual product."
$ref: "#/definitions/LedgerAmount"
approvedAmount:
description: "The transaction amount which was approved by the upstream entity."
$ref: "#/definitions/LedgerAmount"
feeAmount:
description: "Fees charged by the upstream entity for processing the transaction."
$ref: "#/definitions/LedgerAmount"
balanceAmount:
description: "The remaining balance on the customer's account."
$ref: "#/definitions/LedgerAmount"
additionalAmounts:
type: "object"
description: "Any additional amounts that are involved in a transaction which\
\ don't appropriately fit into the other amount fields."
additionalProperties:
$ref: "#/definitions/LedgerAmount"
description: "Amounts which make up the transaction. Absent amounts have zero\
\ value."
Barcode:
type: "object"
required:
- "data"
- "encoding"
properties:
data:
type: "string"
description: "Data to be encoded in the barcode"
encoding:
type: "string"
description: "Specifies the encoding used in the barcode"
description: "Used to indicate barcode information for a slip line."
BasicAdvice:
type: "object"
required:
- "id"
- "requestId"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this advice, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
requestId:
type: "string"
description: "The UUID identifying the request that this advice relates to"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
thirdPartyIdentifiers:
type: "array"
description: "The unaltered thirdPartyIdentifiers array as supplied in the\
\ related BasicResponse message. Required if thirdPartyIdentifiers field\
\ was present in the BasicResponse. If no thirdPartyIdentifiers was received\
\ in the BasicResponse or no BasicResponse was received then this should\
\ be set to the thirdPartyIdentifiers sent in the original request."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
description: "The data required in all advice messages"
BasicReversal:
type: "object"
required:
- "id"
- "requestId"
- "reversalReason"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this advice, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
requestId:
type: "string"
description: "The UUID identifying the request that this advice relates to"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
thirdPartyIdentifiers:
type: "array"
description: "The unaltered thirdPartyIdentifiers array as supplied in the\
\ related BasicResponse message. Required if thirdPartyIdentifiers field\
\ was present in the BasicResponse. If no thirdPartyIdentifiers was received\
\ in the BasicResponse or no BasicResponse was received then this should\
\ be set to the thirdPartyIdentifiers sent in the original request."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "An advice that notifies of the negative completion of a transaction.\
\ This can be either due to customer cancellation, or as a result of receiving\
\ a non-final response (or no response) to a request"
EncryptionParameters:
type: "object"
required:
- "accountNumber"
properties:
pinBlockFormat:
type: "string"
description: "PIN block format that was used when encrypting the PIN. Defaults\
\ to ISO_9564_FORMAT_0."
enum:
- "ISO_9564_FORMAT_0"
- "ISO_9564_FORMAT_1"
- "ISO_9564_FORMAT_3"
default: "ISO_9564_FORMAT_0"
accountNumber:
type: "string"
description: "12 digit account number used when encrypting the PIN. When account\
\ number is a card number (PAN), this is the rightmost 12 digits excluding\
\ the check digit."
pattern: "[0-9]{12}"
keyIndex:
type: "integer"
format: "int32"
description: "Index of the key under which the PIN block is encrypted. Where\
\ keys are exchanged in TR-31 KeyBlock format, this should be set to the\
\ key version number field of the key used for encryption. If this field\
\ is not populated, the most recently exchanged key will be used. Note that\
\ omitting this field may require a higher level of synchronization during\
\ automated key exchange in some environments."
description: "Parameters pertaining to the generation of the PIN block. Required\
\ if the service is to perform any operations on the encrypted PIN, such as\
\ translation."
ErrorDetail:
type: "object"
required:
- "errorMessage"
- "errorType"
- "id"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying the message which caused\
\ the ErrorDetail, as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
originalId:
type: "string"
description: "The UUID of the original request message in the case of an error\
\ occurring for an advice message"
errorType:
type: "string"
description: "The type of error that occurred"
enum:
- "DUPLICATE_RECORD"
- "FORMAT_ERROR"
- "FUNCTION_NOT_SUPPORTED"
- "GENERAL_ERROR"
- "INVALID_AMOUNT"
- "ROUTING_ERROR"
- "TRANSACTION_NOT_SUPPORTED"
- "UNABLE_TO_LOCATE_RECORD"
- "UPSTREAM_UNAVAILABLE"
- "VOUCHER_ALREADY_REDEEMED"
- "VOUCHER_ALREADY_PROVISIONED"
- "VOUCHER_ALREADY_CONFIRMED"
- "VOUCHER_ALREADY_REVERSED"
- "VOUCHER_ALREADY_REFUNDED"
- "VOUCHER_NOT_REFUNDED"
- "VOUCHER_NOT_REDEEMABLE"
- "VOUCHER_NOT_REDEEMED"
- "VOUCHER_STATUS_UNKNOWN"
- "REDEMPTION_ALREADY_CONFIRMED"
- "REDEMPTION_NOT_CONFIRMED"
- "REDEMPTION_ALREADY_REVERSED"
- "REFUND_ALREADY_CONFIRMED"
- "REFUND_ALREADY_REVERSED"
- "INVALID_MERCHANT"
- "INVALID_VOUCHER"
- "AUTHENTICATION_ERROR"
- "INSUFFICIENT_AMOUNT"
- "DO_NOT_HONOUR"
errorMessage:
type: "string"
description: "A short description of the error"
minLength: 0
maxLength: 80
providerErrorCode:
type: "string"
description: "The response code received from the voucher vendor in response\
\ to an operation."
providerErrorMessage:
type: "string"
description: "The error message received from the voucher vendor in response\
\ to an operation."
detailMessage:
type: "object"
description: "A free form detailed description of a particular failure condition\
\ may optionally be supplied"
description: "Represents the reasons an operation has failed."
HashedPinParameters:
type: "object"
required:
- "name"
properties:
name:
type: "string"
description: "The name of the hashing algorithm."
minLength: 0
maxLength: 20
description: "A collection of parameters required to reliably reproduce the hashed\
\ value (excluding the actual PIN value)."
Institution:
type: "object"
required:
- "id"
- "name"
properties:
id:
type: "string"
description: "The institution's ID. API implementations should take care to\
\ set this field as appropriate for the implementation."
name:
type: "string"
description: "The institutions's name"
minLength: 0
maxLength: 40
description: "Originating, acquiring, processing, or receiving institution details"
LedgerAmount:
type: "object"
required:
- "amount"
- "currency"
properties:
amount:
type: "integer"
format: "int64"
description: "Amount in minor denomination, e.g. R799.95 is encoded as 79995"
currency:
type: "string"
description: "Three digit currency number from ISO 4217, e.g. South African\
\ Rand is encoded as 710"
pattern: "[0-9]{3}"
ledgerIndicator:
type: "string"
description: "Indicates whether this amount is a debit or a credit. Only required\
\ when the amount can be either a debit or a credit"
enum:
- "DEBIT"
- "CREDIT"
description: "An amount object only containing value and currency, and optionally\
\ an indicator of DEBIT/CREDIT"
Merchant:
type: "object"
required:
- "merchantId"
- "merchantName"
- "merchantType"
properties:
merchantType:
type: "string"
description: "The assigned four digit merchant category code"
pattern: "[0-9]{4}"
merchantId:
type: "string"
description: "The assigned merchant identifier. Also known as card acceptor\
\ id"
minLength: 15
maxLength: 15
merchantName:
description: "The name of a merchant"
$ref: "#/definitions/MerchantName"
description: "Merchant related data. Must be included if available"
MerchantName:
type: "object"
required:
- "city"
- "country"
- "name"
- "region"
properties:
name:
type: "string"
description: "The merchant or trading as name associated with the merchant"
minLength: 0
maxLength: 23
city:
type: "string"
description: "The city where the merchant is located"
minLength: 0
maxLength: 13
region:
type: "string"
description: "The state or region where the merchant is located"
minLength: 0
maxLength: 2
country:
type: "string"
description: "The country where the merchant is located"
minLength: 0
maxLength: 2
description: "A container object representing the Merchant Name and Location"
Originator:
type: "object"
required:
- "institution"
- "merchant"
- "terminalId"
properties:
institution:
description: "The institution originating the request, as issued by Electrum"
$ref: "#/definitions/Institution"
terminalId:
type: "string"
description: "The ID that uniquely identifies each device or system in an\
\ originator's institution capable of sending requests. Required for transactions\
\ initiated from physical card entry or point-of-sale devices"
minLength: 8
maxLength: 8
merchant:
description: "Merchant data. Required if available"
$ref: "#/definitions/Merchant"
operatorId:
type: "string"
description: "The ID that uniquely identifies the person operating the terminal\
\ specified by the terminalId field."
minLength: 0
maxLength: 30
description: "The Originator object encapsulates data relating to the originator\
\ of the transaction"
Pin:
type: "object"
required:
- "type"
discriminator: "type"
properties:
type:
type: "string"
description: "Whether the PIN is communicated in the clear or encrypted."
enum:
- "CLEAR_PIN"
- "ENCRYPTED_PIN"
- "HASHED_PIN"
description: "Base model for capturing either a clear PIN or encrypted PIN"
PinClear:
allOf:
- $ref: "#/definitions/Pin"
- type: "object"
required:
- "pin"
properties:
pin:
type: "string"
description: "A clear PIN"
pattern: ".{0,20}"
description: "A clear PIN required to authorise a transaction."
PinEncrypted:
allOf:
- $ref: "#/definitions/Pin"
- type: "object"
required:
- "pinBlock"
properties:
pinBlock:
type: "string"
description: "Hexadecimal string representing the encrypted PIN to be used."
pattern: "[a-fA-F0-9]{16}"
encryptionParameters:
description: "Parameters pertaining to the generation of the pinBlock. Required\
\ if the service is to perform any operations on the encrypted PIN, such\
\ as PIN translation."
$ref: "#/definitions/EncryptionParameters"
description: "A PIN required to authorise a transaction. EncryptionParameters\
\ should be provided where the service will be performing operations on the\
\ encrypted PIN, such as PIN translation. Only the PIN block need be provided\
\ where the service is expected to forward it to a third party, where the\
\ calling client and said third party have agreed upon encryption parameters\
\ beforehand."
PinHashed:
allOf:
- $ref: "#/definitions/Pin"
- type: "object"
required:
- "hash"
properties:
hash:
type: "string"
description: "A hashed PIN expressed as an ASCII string of hexadecimal values."
pattern: "[0-9,A-F]{1,512}"
hashedPinParameters:
description: "Parameters that describe the hashing algorithm used to hash\
\ the PIN."
$ref: "#/definitions/HashedPinParameters"
description: "A PIN, required to authorise a transaction, which has been hashed\
\ according to some hashing algorithm."
Product:
type: "object"
required:
- "productId"
properties:
productId:
type: "string"
description: "A vendor determined code identifying the product the voucher\
\ should pertain to."
pattern: "[0-9A-Za-z]{1,20}"
barcode:
type: "string"
description: "A barcode code identifying the product. This is an alternative\
\ identifier for the product but does not supersede the productId."
pattern: "[0-9A-Za-z]{1,13}"
name:
type: "string"
description: "The name of the product."
minLength: 1
maxLength: 40
description: "Product related data."
ProvisionRequest:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "If the voucher identified by the voucher field is not a fixed\
\ price product then the amounts field indicates the value of the product\
\ referred to."
$ref: "#/definitions/Amounts"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction."
items:
$ref: "#/definitions/Tender"
voucher:
description: "The voucher that is being requested for provisioning."
$ref: "#/definitions/Voucher"
product:
description: "The product for which the voucher should be provisioned."
$ref: "#/definitions/Product"
description: "Information about the voucher provision request."
ProvisionResponse:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "voucher"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "The amounts for which a single use voucher is provisioned for."
$ref: "#/definitions/Amounts"
voucher:
description: "The voucher provisioned if the vendor processed the request\
\ successfully."
$ref: "#/definitions/Voucher"
product:
description: "The product for which the voucher was provisioned. This should\
\ be the same as the product in the ProvisionRequest and is echoed back\
\ for convenience."
$ref: "#/definitions/Product"
description: "Information about the voucher provisioned."
RedemptionRequest:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "voucher"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
voucher:
description: "The voucher to be redeemed."
$ref: "#/definitions/Voucher"
amounts:
description: "Indicates the amount for which the voucher is to be redeemed."
$ref: "#/definitions/Amounts"
description: "A description of a request to redeem a voucher. This object supports\
\ requests for redemptions against amounts different to the value for which\
\ the voucher was provisioned."
RedemptionResponse:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
voucher:
description: "Describes the voucher provisioned by the vendor."
$ref: "#/definitions/Voucher"
amounts:
description: "Amounts which make up the transaction. Absent amounts have zero\
\ value."
$ref: "#/definitions/Amounts"
description: "Information about the voucher redemption outcome."
RefundRequest:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "voucher"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "Indicates the amount for which the voucher should be refunded\
\ in the requestAmount field. If requestAmount is not populated then a full\
\ refund is to be assumed."
$ref: "#/definitions/Amounts"
voucher:
description: "The voucher to be refunded."
$ref: "#/definitions/Voucher"
redemptionId:
type: "string"
description: "Carries the value of the `id` field of the RedemptionRequest\
\ which is being refunded. Use of this field is encouraged if the refund\
\ request is submitted to the same system which processed the original redemption."
receiverTransactionRef:
type: "string"
description: "Carries the value of the receiver's transaction reference for\
\ the original redemption. Use of this field is specifically encouraged\
\ if: The voucher alone is not enough to uniquely identify the redemption\
\ to be refunded or the refund is processed by any system which did not\
\ process the original redemption. Use of this field is generally encouraged\
\ as it provides the receiver (who ultimately processed the redemption)\
\ with their specific transaction reference for the redemption. This may\
\ aid their processing of the refund."
description: "A description of a request to refund a voucher. This object supports\
\ requests for refunds for amounts different to the value for which the voucher\
\ was originally redeemed. Refunds are predicated on some prior redemption which\
\ may be referenced using a variety of mechanisms: the voucher used (if a voucher\
\ may only ever be used once), the redemption's message ID (which links to a\
\ specific redemption if a voucher may be re-issued by a voucher vendor), or\
\ the receiver's transaction reference for the redemption (most readily identifies\
\ the specific redemption to the receiver)."
RefundResponse:
type: "object"
required:
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this transaction, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
originator:
description: "Data relating to the originator of the transaction."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of Transaction."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which each identify the transaction\
\ within each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
slipData:
description: "Text to be printed on the customer receipt."
$ref: "#/definitions/SlipData"
basketRef:
type: "string"
description: "Used to group multiple transactions which would otherwise be\
\ considered independent."
tranType:
type: "string"
description: "Data relating to the type of transaction taking place (i.e.\
\ cash withdrawal, goods and services etc.)."
enum:
- "GOODS_AND_SERVICES"
- "CASH_WITHDRAWAL"
- "DEBIT_ADJUSTMENT"
- "GOODS_AND_SERVICES_WITH_CASH_BACK"
- "NON_CASH"
- "RETURNS"
- "DEPOSIT"
- "CREDIT_ADJUSTMENT"
- "GENERAL_CREDIT"
- "AVAILABLE_FUNDS_INQUIRY"
- "BALANCE_INQUIRY"
- "GENERAL_INQUIRY"
- "CARD_VERIFICATION_INQUIRY"
- "CARDHOLDER_ACCOUNTS_TRANSFER"
- "GENERAL_TRANSFER"
- "PAYMENT_FROM_ACCOUNT"
- "GENERAL_PAYMENT"
- "PAYMENT_TO_ACCOUNT"
- "PAYMENT_FROM_ACCOUNT_TO_ACCOUNT"
- "PLACE_HOLD_ON_CARD"
- "GENERAL_ADMIN"
- "CHANGE_PIN"
- "CARD_HOLDER_INQUIRY"
- "POINTS_INQUIRY"
srcAccType:
type: "string"
description: "This specifies the type of source account being used in the\
\ transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
destAccType:
type: "string"
description: "This specifies the type of destination account being used in\
\ the transaction (i.e. cheque, savings)."
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "GIFT_CARD"
- "STORED_VALUE"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "Indicates the amount for which the voucher was refunded. "
$ref: "#/definitions/Amounts"
voucher:
description: "The voucher that was refunded."
$ref: "#/definitions/Voucher"
description: "Information about the voucher redemption outcome."
SlipData:
type: "object"
properties:
messageLines:
type: "array"
description: "An array of text lines and optional formatting to be printed\
\ on the customer slip."
items:
$ref: "#/definitions/SlipLine"
slipWidth:
type: "integer"
format: "int32"
description: "The width of the slip in normal (unformatted) characters."
issuerReference:
type: "string"
description: "An identifier that is printed on the customer slip and uniquely\
\ identifies the payment on the service provider's system. This value is\
\ used by the customer to request a refund when the service supports this\
\ function, and it is thus important that this number is unique."
pattern: "[A-Z0-9]{1,40}"
description: "Data that may be printed on the customer slip for information purposes"
SlipLine:
type: "object"
required:
- "text"
properties:
barcode:
description: "Barcode information for this line"
$ref: "#/definitions/Barcode"
text:
type: "string"
description: "Text contained on the line"
fontWidthScaleFactor:
type: "number"
format: "double"
description: "Scale factor for font width. Assume 1.0 (i.e. normal size) if\
\ not present."
fontHeightScaleFactor:
type: "number"
format: "double"
description: "Scale factor for font height. Assume 1.0 (i.e. normal size)\
\ if not present."
line:
type: "boolean"
description: "Denotes a solid line on the slip. Assume false if not present."
default: false
cut:
type: "boolean"
description: "Indicates the slip should be cut at this line. Assume false\
\ if not present."
default: false
description: "A line of text to be printed on the till slip"
Tender:
type: "object"
required:
- "amount"
- "tenderType"
properties:
accountType:
type: "string"
description: "The type of account"
enum:
- "DEFAULT"
- "SAVINGS"
- "CHEQUE"
- "CREDIT"
- "UNIVERSAL"
- "ELECTRONIC_PURSE"
- "STORED_VALUE"
amount:
description: "The tendered amount"
$ref: "#/definitions/LedgerAmount"
cardNumber:
type: "string"
description: "A PCI compliant masked card number, with at least the first\
\ 6 digits in the clear. Only applicable to card based transactions"
pattern: "[0-9]{6}[0-9*]{0,13}"
reference:
type: "string"
description: "A free text reference"
minLength: 0
maxLength: 40
tenderType:
type: "string"
description: "The type of tender used"
enum:
- "CASH"
- "CHEQUE"
- "CREDIT_CARD"
- "DEBIT_CARD"
- "WALLET"
- "ROUNDING"
- "GIFT_CARD"
- "LOYALTY_CARD"
- "OTHER"
description: "Details of the Tender used by a customer towards a payment"
TenderAdvice:
type: "object"
required:
- "id"
- "requestId"
- "tenders"
- "thirdPartyIdentifiers"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this advice, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)"
requestId:
type: "string"
description: "The UUID identifying the request that this advice relates to"
time:
type: "string"
format: "date-time"
description: "The date and time of the message as recorded by the sender.\
\ The format shall be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\
\ It is recommended that the optional time-secfrac be included up to millisecond\
\ precision"
thirdPartyIdentifiers:
type: "array"
description: "The unaltered thirdPartyIdentifiers array as supplied in the\
\ related BasicResponse message. Required if thirdPartyIdentifiers field\
\ was present in the BasicResponse. If no thirdPartyIdentifiers was received\
\ in the BasicResponse or no BasicResponse was received then this should\
\ be set to the thirdPartyIdentifiers sent in the original request."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
rrn:
type: "string"
description: "This is a reference set by the original source of the transaction."
amounts:
description: "Communicates the final amount for a transaction in the approvedAmount\
\ field. If absent from a reversal then a full reversal is implied (i.e.\
\ a final amount of zero). If absent from a confirmation then a full confirmation\
\ is implied (i.e. the final amount is the same as the approvedAmount of\
\ the authorisation response). The approvedAmount in an advice message\
\ should be less than or equal to the approvedAmount of the authorisation\
\ response as stand-in transactions are not currently supported."
$ref: "#/definitions/Amounts"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction"
items:
$ref: "#/definitions/Tender"
description: "An advice that notifies of the successful completion of a transaction."
ThirdPartyIdentifier:
type: "object"
required:
- "institutionId"
- "transactionIdentifier"
properties:
institutionId:
type: "string"
description: "The entity's institution ID."
transactionIdentifier:
type: "string"
description: "The identifier assigned to this transaction by the institution\
\ represented in institutionId. This value should be unique within the institution's\
\ system."
description: "An identifier assigned by an entity which process the message. Identifiers\
\ are keyed by institution ID thereby enabling any institution to recall a transaction\
\ within the entity's own system using the entity's own identifier. Entity's\
\ must not alter the identifier set by another entity. Once an identifier has\
\ been set by an entity, all other entity's must send that identifier in subsequent\
\ messages."
Voucher:
type: "object"
properties:
code:
type: "string"
description: "The voucher’s code used by the customer to redeem the voucher.\
\ This must be present in ProvisionResponse, RedemptionRequest and RefundRequest\
\ messages. This may be present in a ProvisionRequest if the voucher vendor\
\ allows the client to set the voucher code. It is recommended this field\
\ not be populated in other instances as it may be considered sensitive\
\ data."
minLength: 0
maxLength: 40
expiryDate:
type: "string"
format: "date-time"
description: "The date and time at which the voucher expires. The format shall\
\ be as defined for date-time in [RFC 3339 section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6)."
redeemInstructions:
type: "array"
description: "An array of free text lines which provide the customer with\
\ information on how to redeem the voucher. These are intended to be printed\
\ on a customer's receipt slip."
items:
type: "string"
serialNumber:
type: "string"
description: "The voucher's serial number. This can be used to identify the\
\ voucher in the vendor's system but cannot be used to redeem the voucher."
minLength: 0
maxLength: 40
pin:
description: "A secret value which is required to be provided by a customer\
\ when redeeming the voucher using the code. Use of a PIN in addition to\
\ the voucher code adds security to the voucher redemption process."
$ref: "#/definitions/Pin"
description: "Specifically describes the voucher provisioned by the vendor."
VoucherLookupResponse:
type: "object"
required:
- "voucher"
properties:
settlementEntity:
description: "Information about who the request was routed to for processing."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which issued the voucher."
$ref: "#/definitions/Institution"
amounts:
description: "The amounts for which the single use voucher is provisioned\
\ for. If available, the monetary value of the voucher should be specified\
\ as a CREDIT amount in the approvedAmount field."
$ref: "#/definitions/Amounts"
voucher:
description: "Available details about the voucher."
$ref: "#/definitions/Voucher"
product:
description: "The product for which the voucher was provisioned."
$ref: "#/definitions/Product"
description: "Information about a voucher such as its expiry date, its value and\
\ which entity the voucher belongs to."