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 QR Payment Service describes an interface for supporting\
\ payments via scanning of a QR code transactions."
version: "1.11.0"
title: "QR PaymentService 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: "/qr/v1"
schemes:
- "https"
paths:
/payments:
post:
summary: "Requests a payment to be processed via a QR Partner."
description: "This request contains conventional payment information (POS information,\
\ transaction amount, date etc.) as well as Partner information. If a merchant\
\ is unable to supply the Partner information in this request, then the request\
\ is directed to an intermediate system which also receives notifications\
\ from Partners of QR scans. This intermediate system will match the payment\
\ request from the merchant with the scan notification from the Partner using\
\ the QR code information common to both messages. The payment request may\
\ then be forwarded to the correct Partner for processing."
operationId: "pay"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A QR payment request."
required: true
schema:
$ref: "#/definitions/PaymentRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/PaymentResponse"
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: []
/payments/confirmations:
post:
summary: "Confirms completion of tender initiated by a payment request."
description: "This operation confirms that a QR payment transaction has completed\
\ successfully between the consumer and the merchant. Such a transaction may\
\ be settled between the merchant and the Partner that processed the payment.\
\ Such a transaction cannot be reversed."
operationId: "confirmPayment"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A QR payment confirmation."
required: true
schema:
$ref: "#/definitions/PaymentConfirmation"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/PaymentConfirmation"
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: []
/payments/reversals:
post:
summary: "Reverses a payment request that failed or timed out"
description: "This operation indicates that the sale did not complete and the\
\ payment should be reversed if it took place. Once a payment is reversed\
\ it cannot be confirmed and need not be settled between the merchant and\
\ the QR Partner."
operationId: "reversePayment"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A QR payment reversal."
required: true
schema:
$ref: "#/definitions/PaymentReversal"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/PaymentReversal"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ErrorDetail"
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: []
/qrCodes:
post:
summary: "Requests a QR Code to display to a customer to be scanned."
description: "The customer may scan this code with a Partner's application and\
\ thereby allow the Partner to identify the QR code provider."
operationId: "createQrCode"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Information pertaining to the QR code, which may be available\
\ at the time of the request. This may include details such as the entity\
\ requesting the QR code, the value of the transaction for which the QR\
\ code will be used and the specific purpose of the QR code. The request\
\ for a QR code should convey information about the merchant requesting\
\ the QR code (e.g. POS information) and not information about the consumer\
\ who will scan the QR code (e.g. customer or loyalty information)."
required: true
schema:
$ref: "#/definitions/CreateQrCodeRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/CreateQrCodeResponse"
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: []
/scans:
post:
summary: "Notify that a QR code has been scanned."
description: "Partners are not notified by a QR code provider when a QR code\
\ is generated. Only when a consumer scans a QR code using a Partner's application\
\ is the Partner aware that the QR code is available. The Partner subsequently\
\ informs the provider of the QR code that their code has been scanned. The\
\ QR code provider shall then associate any other transactions pertaining\
\ to the QR code with the Partner."
operationId: "notifyScan"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "A get QR code request."
required: true
schema:
$ref: "#/definitions/ScanNotification"
responses:
202:
description: "Accepted"
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: []
securityDefinitions:
httpBasic:
description: "All requests require HTTP basic authentication, where user name\
\ equals the value used in Client.id and password has been agreed with Electrum."
type: "basic"
definitions:
AccountPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
properties:
srcAccountId:
type: "string"
description: "Source AccountId from which this payment will be made."
srcCustomerId:
type: "string"
description: "Source CustomerId from which this payment will be made."
destAccountId:
type: "string"
description: "Destination AccountId to which this payment will be made."
destCustomerId:
type: "string"
description: "Destination CustomerId to which this payment will be made."
description: "Model for an account-to-account payment method"
Address:
type: "object"
properties:
addressLine1:
type: "string"
description: "First line of street address."
pattern: "^.{1,100}"
addressLine2:
type: "string"
description: "Second line of street address (if required)."
pattern: "^.{1,100}"
city:
type: "string"
description: "The city where the owner is located. Note: if this field ever\
\ needs to be translated to another API with shorter fields, the field will\
\ be truncated from the right."
pattern: "^.{1,30}"
region:
type: "string"
description: "The state or region where the owner is located."
pattern: "[A-Z]{2}"
country:
type: "string"
description: "The owner's resident country expressed as an ISO 3166-1 Alpha-2\
\ code."
pattern: "[A-Z]{2}"
postalCode:
type: "string"
description: "The owner's postal code."
pattern: "[A-Za-z0-9 -]{1,20}"
description: "Details of a customer's address"
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."
An32TokenPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "token"
properties:
token:
type: "string"
description: "32 character alphanumeric code which identifies a token"
pattern: "[a-zA-Z0-9]{32}"
description: "Model for token-based payments"
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."
CardPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "pan"
properties:
posInfo:
$ref: "#/definitions/PosInfo"
pin:
description: "The PIN associated with this card as either a clear PIN or\
\ an encrypted PIN in HEX format."
$ref: "#/definitions/Pin"
pan:
type: "string"
description: "Primary account number that uniquely identifies this card."
pattern: "[0-9]{1,19}"
expiryDate:
type: "string"
description: "The card expiry date, in YYMM format."
pattern: "[0-9]{4}"
encryptedPin:
description: "The encrypted pin number associated with the card in HEX format."
$ref: "#/definitions/EncryptedPin"
description: "Model for card-based payments"
CreateQrCodeRequest:
type: "object"
required:
- "client"
- "id"
- "originator"
- "time"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this request. This may\
\ be a variant 3 or 4 as defined 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 request."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of 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"
rrn:
type: "string"
description: "This is a reference set by the original source of the request."
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
amounts:
description: "The amounts pertaining to the QR code to be created."
$ref: "#/definitions/Amounts"
customer:
description: "Information detail pertaining to the customer."
$ref: "#/definitions/Customer"
qrProperties:
description: "A collection of attributes that describe how a QR code is intended\
\ to be used for transacting."
$ref: "#/definitions/QrProperties"
paymentMethods:
type: "array"
description: "A list of payment methods with which the QR owner will accept\
\ payment. The paymentMethods specify the destination to which funds may\
\ be transferred when the QR code is scanned."
items:
$ref: "#/definitions/PaymentMethod"
description: "A request from the merchant for a QR code to be generated. The QR\
\ code returned should be suitable to be displayed to a consumer to be scanned."
CreateQrCodeResponse:
type: "object"
required:
- "client"
- "id"
- "originator"
- "qrCode"
- "time"
- "tranId"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this request. This may\
\ be a variant 3 or 4 as defined 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 request."
$ref: "#/definitions/Originator"
client:
description: "Data relating to the sender of 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"
rrn:
type: "string"
description: "This is a reference set by the original source of the request."
stan:
type: "string"
description: "The System Trace Audit Number can be used to locate transactions\
\ across different systems."
amounts:
description: "The amounts pertaining to the QR code to be created."
$ref: "#/definitions/Amounts"
customer:
description: "Information detail pertaining to the customer."
$ref: "#/definitions/Customer"
qrProperties:
description: "A collection of attributes that describe how a QR code is intended\
\ to be used for transacting."
$ref: "#/definitions/QrProperties"
paymentMethods:
type: "array"
description: "A list of payment methods with which the QR owner will accept\
\ payment. The paymentMethods specify the destination to which funds may\
\ be transferred when the QR code is scanned."
items:
$ref: "#/definitions/PaymentMethod"
tranId:
type: "string"
description: "The unique transaction identifier assigned by the QR code provider\
\ to this QR code. This value is also encoded in the QR code returned in\
\ the qrCode field. The QR code provider is responsible for ensuring appropriate\
\ uniqueness of the QR code for the appropriate period of time. No specific\
\ restrictions are placed on the format of the QR code (length, characters\
\ etc.) but implementors should consider the following aspects; ***Length***\
\ - Longer QR codes require more detailed resolution on display screens\
\ and scanning devices and are also harder to scan. ***Manual Entry*** -\
\ While manual entry of QR codes is not explicitly supported by the QR Payments\
\ Service Interface, implementors may choose to support such fallback mechanisms\
\ if a QR code cannot be scanned. Longer and more complicated codes will\
\ be more susceptible to errors when inputted manually. This value must\
\ be provided in subsequent 'notifyScan' and 'pay' operations to link payments\
\ to specific Partners."
qrCode:
type: "string"
description: "The full set of data to be encoded in the graphical QR code.\
\ The data is provided in a Tag-Length-Value format as described in the\
\ EMVCo specification but is not a fully EMVCo compliant string e.g. Tags\
\ which are mandatory under the EMVCo specification may be omitted. The\
\ precise set of Tags to be populated in the QR code should be discussed\
\ and agreed upon by implementation partners."
description: "The response to a CreateQrCodeRequest which contains the specific\
\ code assigned by the QR code provider as well as the full QR code in EMVCo\
\ format."
Customer:
type: "object"
properties:
firstName:
type: "string"
description: "The customer's first name(s)"
minLength: 0
maxLength: 40
lastName:
type: "string"
description: "The customer's last name"
minLength: 0
maxLength: 40
address:
type: "string"
description: "The customer's address"
minLength: 0
maxLength: 80
dateOfBirth:
type: "string"
format: "date-time"
description: "The customer's date of birth"
status:
type: "string"
description: "The status of this customer on the Giftcard system. For example:\
\ active, inactive"
msisdn:
type: "string"
description: "This must conform to the ITU E.164 numbering plan (https://www.itu.int/rec/T-REC-E.164/en)\
\ e.g. 27821234567 for a South African number."
pattern: "^\+?[1-9]\d{0,14}"
emailAddress:
type: "string"
format: "email"
description: "The customer's email address. This address must conform to RFC\
\ 5322 3.4.1 addr-spec (https://tools.ietf.org/html/rfc5322#section-3.4.1)."
addressDetails:
description: "The customer's address details."
$ref: "#/definitions/Address"
profileId:
type: "string"
description: "The customer's profile ID. Used to uniquely identify a customer."
description: "A customer who ultimately requests a transaction be performed."
CustomerProvidedValuePrompt:
type: "object"
required:
- "label"
properties:
label:
type: "string"
description: "Label that will be displayed as prompt for the customer-provided\
\ value. This value should also uniquely identify the prompt and its associated\
\ value once captured."
minLength: 0
maxLength: 50
description: "Properties of a prompt that can be displayed on a customer's scanning\
\ application to capture a user-provided text value which can be used when performing\
\ actions associated with the data embedded in this QR code."
EncryptedPin:
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."
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."
default: "ISO_9564_FORMAT_0"
enum:
- "ISO_9564_FORMAT_0"
- "ISO_9564_FORMAT_1"
- "ISO_9564_FORMAT_3"
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 this errorDetail, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
minLength: 0
maxLength: 20
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. This value should be used for\
\ programmatic handling of errors."
enum:
- "DUPLICATE_RECORD"
- "FORMAT_ERROR"
- "FUNCTION_NOT_SUPPORTED"
- "GENERAL_ERROR"
- "INVALID_AMOUNT"
- "ROUTING_ERROR"
- "TRANSACTION_NOT_SUPPORTED"
- "UNABLE_TO_LOCATE_RECORD"
- "UPSTREAM_UNAVAILABLE"
- "ACCOUNT_ALREADY_SETTLED"
- "INVALID_MERCHANT"
- "DO_NOT_HONOR"
- "DECLINED_BY_PARTNER"
- "DECLINED_BY_ACQUIRER"
- "DECLINED_BY_ISSUER"
- "INSUFFICIENT_FUNDS"
- "INVALID_CARD_NUMBER"
- "CARD_EXPIRED"
- "INVALID_TRAN_ID"
- "PARTNER_UNKNOWN"
- "NO_SCAN_RECEIVED"
- "INVALID_ACCOUNT"
errorMessage:
type: "string"
description: "A short description of the error. This value should be suitable\
\ for display to an operator."
minLength: 0
maxLength: 40
detailMessage:
type: "object"
description: "A free form detailed description of a particular failure condition\
\ may optionally be supplied. This information is intended for informational\
\ purposes only when investigating the cause of a failure."
providerErrorCode:
type: "string"
description: "The error code returned by the service provider if available.\
\ Note that this should be used for informational purposes only. Messages\
\ displayed on the POS should make use of errorType and errorMessage to\
\ ensure a consistent set of responses."
providerErrorMsg:
type: "string"
description: "The error message returned by the service provider if available.\
\ Note that this should be used for informational purposes only. Messages\
\ displayed on the POS should make use of errorType and errorMessage to\
\ ensure a consistent set of responses."
providerRef:
type: "string"
description: "The reference returned by the service provider if available."
tranId:
type: "string"
description: "The unique transaction identifier related to this transaction\
\ if available. This is the value returned in the tranId field of the CreateQrCodeResponse\
\ or the ScanNotification."
description: "Describes a failed outcome of an operation."
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"
LoyaltyCardPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "cardNumber"
properties:
cardNumber:
type: "string"
description: "Primary account number of the loyalty programme card used\
\ to make a payment"
pattern: "[0-9]{16}"
description: "Model for payments made using loyalty programme cards"
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"
NotificationParameters:
type: "object"
properties:
recipients:
type: "array"
description: "A list of entities that should receive notifications based on\
\ the use of a QR code."
items:
$ref: "#/definitions/NotificationRecipient"
description: "Some integrations that make use of this interface may support notifying\
\ recipients when QR data has been used to perform some action. For example,\
\ a recipient may receive a notification if a customer successfully makes a\
\ payment by scanning a QR code. This property contains details describing notifications\
\ that may be triggered by using this QR code. Note that this data may be omitted\
\ in lookup operation responses, as this data may be considered sensitive."
NotificationRecipient:
type: "object"
properties:
emailAddress:
type: "string"
format: "email"
description: "An email address where a recipient should receive a notification\
\ based on use of a QR code."
msisdn:
type: "string"
description: "An MSISDN where a recipient should receive a notification based\
\ on use of a QR code. This must conform to the ITU E.164 numbering plan\
\ (https://www.itu.int/rec/T-REC-E.164/en) e.g. +27821234567 for a South\
\ African number."
pattern: "^\+?[1-9][0-9]{1,14}"
description: "An entity that should receive notifications based on the use of\
\ a QR code. This model collects details about how to contact the recipient."
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
channelId:
type: "string"
description: "The ID that uniquely identifies the originator's channel that\
\ this transaction was received through."
minLength: 0
maxLength: 50
description: "The Originator object encapsulates data relating to the originator\
\ of the transaction"
PaymentConfirmation:
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"
partner:
description: "An echo of the value in the original PaymentRequest."
$ref: "#/definitions/Institution"
tranId:
type: "string"
description: "An echo of the value in the original PaymentRequest."
description: "Confirm that a previous PaymentRequest has completed successfully\
\ at the POS. Where possible all optional fields should be supplied to ensure\
\ smooth processing. If optional fields are not present then processing may\
\ require retrieval of the original transaction leading to unnecessary processing\
\ overheads."
PaymentMethod:
type: "object"
required:
- "type"
discriminator: "type"
properties:
type:
type: "string"
description: "The general method of payment used"
enum:
- "AN_32_TOKEN"
- "LOYALTY_CARD"
- "CARD"
- "ACCOUNT"
- "REWARD"
- "WALLET"
- "QR"
name:
type: "string"
description: "The specific method of payment used"
amount:
description: "Ledger amount of the payment"
$ref: "#/definitions/LedgerAmount"
issuer:
description: "The institution which is responsible for managing this payment\
\ method (e.g. the card issuer, the wallet provider, the token provider\
\ etc.)"
$ref: "#/definitions/Institution"
pin:
description: "The PIN associated with this payment method. Various PIN formats\
\ are supported (clear, encrypted, hashed etc.). NOTE: A pin is not expected\
\ in a response and will not be translated."
$ref: "#/definitions/Pin"
proxy:
type: "string"
description: "An alternative identifier for the customer's source of funds.\
\ Acts as a stand in for the customer identifier. E.g. a customer's MSISDN\
\ or email address."
minLength: 0
maxLength: 40
proxyType:
type: "string"
description: "An enumerated value describing the type of value used as the\
\ proxy."
enum:
- "MSISDN"
- "EMAIL"
- "UNKNOWN"
description: "Base model for all payment types"
PaymentRequest:
type: "object"
required:
- "amounts"
- "client"
- "id"
- "originator"
- "thirdPartyIdentifiers"
- "time"
- "tranId"
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."
partner:
description: "Data relating to the entity who will process the payment. This\
\ identifies the entity who provided the ScanNotification for the QR code\
\ associated with this PaymentRequest. This should be populated if known\
\ to aid in routing the PaymentRequest to the entity which provided the\
\ ScanNotification."
$ref: "#/definitions/Institution"
amounts:
description: "The amounts pertaining to the transaction. Note that the requestAmount\
\ herein maybe be different to that submitted when the QR code was requested.\
\ This request amount describes the actual amount to be processed in the\
\ transaction."
$ref: "#/definitions/Amounts"
tranId:
type: "string"
description: "The unique transaction identifier related to this transaction.\
\ Retailers must set this to the same value as that returned in the tranId\
\ field of the CreateQrCodeResponse that preceded this PaymentRequest. Partners\
\ may associate this PaymentRequest with the QR code whose ScanNotification\
\ they submitted with this value."
partnerPaymentToken:
type: "string"
description: "A payment token received from the Partner in the ScanNotification.\
\ A Partner may provide such a value in the ScanNotification so that it\
\ is included in the PaymentRequest to the Partner. This field should be\
\ populated if known. A Partner may expect to receive this value in the\
\ PaymentRequest if it was provided in the ScanNotification."
description: "A request to effect a payment with a linked QR code. Such requests\
\ originate from the Merchant's system and are typically directed to the Partner\
\ for processing. If the Partner for a PaymentRequest is not known, then the\
\ PaymentRequest may be directed to an intermediate system which receives ScanNotification\
\ messages from Partners. This intermediate system is then responsible for identifying\
\ the correct Partner to which a PaymentRequest should be directed."
PaymentResponse:
type: "object"
required:
- "amounts"
- "client"
- "id"
- "originator"
- "partner"
- "thirdPartyIdentifiers"
- "time"
- "tranId"
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."
partner:
description: "Data relating to the entity who processed the PaymentRequest.\
\ This identifies the entity who provided the ScanNotification for the QR\
\ code associated with this payment."
$ref: "#/definitions/Institution"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction. This may\
\ be used to describe the payment which was effected as a result of the\
\ QR code scan e.g. the card detail ultimately used for the payment."
items:
$ref: "#/definitions/Tender"
amounts:
description: "The amounts pertaining to the transaction."
$ref: "#/definitions/Amounts"
tranId:
type: "string"
description: "This value is echoed from the PaymentRequest."
partnerPaymentToken:
type: "string"
description: "This value is echoed from the PaymentRequest."
description: "The response to a successful payment with a linked QR code scan."
PaymentReversal:
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"
partner:
description: "An echo of the value in the original PaymentRequest."
$ref: "#/definitions/Institution"
tranId:
type: "string"
description: "An echo of the value in the original PaymentRequest."
description: "Reverse a previous PaymentRequest. This may be due to a cancellation\
\ at the POS or because the original PaymentRequest failed or is in an unknown\
\ state. Where possible all optional fields should be supplied to ensure smooth\
\ processing. If optional fields are not present then processing may require\
\ retrieval of the original transaction leading to unnecessary processing overheads."
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."
PosEntryMode:
type: "object"
required:
- "panEntryMode"
- "pinEntryCapability"
properties:
panEntryMode:
type: "string"
description: "Describes the method by which the PAN was captured."
enum:
- "UNKNOWN"
- "MANUAL"
- "MAGSTRIPE_NO_CVV"
- "BARCODE"
- "OCR"
- "ICC_CVV"
- "CONTACTLESS_ICC"
- "MAGSTRIPE_CVV"
- "CONTACTLESS_MAGSTRIPE"
- "ICC_NO_CVV"
- "ORIG_MODE"
- "FALLBACK"
pinEntryCapability:
type: "string"
description: "Describes whether the PIN can be entered."
enum:
- "UNKNOWN"
- "CAN_ACCEPT"
- "CANNOT_ACCEPT"
description: "Describes how the PAN and PIN were captured by the POS."
PosInfo:
type: "object"
properties:
entryMode:
description: "Describes the manner in which the POS captured card and PIN\
\ data."
$ref: "#/definitions/PosEntryMode"
posConditionCode:
type: "string"
description: "Describes the circumstances of the transaciton at the POS."
enum:
- "NORMAL_PRESENTMENT"
- "CUSTOMER_NOT_PRESENT"
- "CUSTOMER_PRESENT_AND_CARD_NOT_PRESENT"
- "CUSTOMER_IDENTITY_VERIFIED"
- "PUBLIC_UTILITY_TERMINAL"
- "CUSTOMER_TERMINAL"
- "MANUAL_REVERSAL"
- "UNATTENDED_TERMINAL_AND_CARD_CAN_BE_RETAINED"
- "UNATTENDED_TERMINAL_AND_CARD_CANNOT_BE_RETAINED"
description: "POS related data."
QrPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "tranId"
properties:
tranId:
type: "string"
description: "The unique transaction identifier related to this transaction.\
\ In QRs styled on the EMVCo specification, the tranId is embedded in\
\ sub-Tag 00 of the Electrum MAIT."
partnerPaymentToken:
type: "string"
description: "A payment token received from the Partner."
description: "Model for QR-based payments. This payment method should be used\
\ when a QR code is presented for payment."
QrProperties:
type: "object"
properties:
description:
type: "string"
description: "The description field is intended to be displayed to the person\
\ scanning the QR code to provide them with context for the QR and why it\
\ was created."
minLength: 0
maxLength: 20
guid:
type: "string"
description: "The value which, when embedded in an EMVCo QR code, identifies\
\ the provider of the QR code."
overPaymentAllowed:
type: "boolean"
description: "Indicates whether or not the transaction against the QR may\
\ use an amount greater than the value in the `amount` field."
default: false
partPaymentAllowed:
type: "boolean"
description: "Indicates whether or not the transaction against the QR may\
\ use an amount less than the value in the `amount` field."
default: false
customerProvidedValuePrompts:
type: "array"
description: "Details for prompts that can be displayed to the customer by\
\ a scanning application. These prompts can be used to signal that the user\
\ can input their own custom text values when scanning a QR code. These\
\ values may then be used as part of the action that is initiated by scanning\
\ the code."
items:
$ref: "#/definitions/CustomerProvidedValuePrompt"
requestTip:
type: "boolean"
description: "When a QR code is used for facilitating payment, this option\
\ can be used to indicate that a prompt for a separate tip amount should\
\ be displayed by the customer's scanning application. This value is not\
\ required, so when this property is not specified, this value should be\
\ treated as `false`."
default: false
expiryDate:
type: "string"
format: "date-time"
description: "The date and time at which the QR code expires at which point\
\ it may no longer be used to facilitate transactions. 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"
notificationParameters:
description: "Some integrations that make use of this interface may support\
\ notifying recipients when QR data has been used to perform some action.\
\ For example, a recipient may receive a notification if a customer successfully\
\ makes a payment by scanning a QR code. This property contains details\
\ describing notifications that may be triggered by using this QR code.\
\ Note that this data may be omitted in lookup operation responses, as this\
\ data may be considered sensitive."
$ref: "#/definitions/NotificationParameters"
qrLabel:
type: "string"
description: "This value can be used as an alternative means of referencing\
\ a QR code. It supports a potentially human-readable way to reference a\
\ QR code that may be easily recognised by the owner or users of the code."
minLength: 0
maxLength: 50
description: "A collection of attributes that describe how a QR code is intended\
\ to be used for transacting."
RewardPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "rewardCode"
properties:
rewardCode:
type: "string"
description: "A code used to recognise the reward programme"
minLength: 0
maxLength: 40
description: "Model for reward-based payments. This payment method should be\
\ used when the payment is offset using a reward programme"
ScanNotification:
type: "object"
required:
- "id"
- "partner"
- "time"
- "tranId"
properties:
id:
type: "string"
description: "The randomly generated UUID identifying this notification. This\
\ may be a variant 3 or 4 as defined 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"
partner:
description: "Data relating to the entity whose customer scanned a QR code.\
\ PaymentRequest messages which have a matching tranId value should be be\
\ sent to the Partner for processing."
$ref: "#/definitions/Institution"
settlementEntity:
description: "Data relating to the entity with whom the Merchant will settle\
\ the transaction. A Partner may provide this information if known at the\
\ time the QR code was scanned."
$ref: "#/definitions/Institution"
receiver:
description: "Data relating to the entity which ultimately processes the request.\
\ A Partner may provide this information if known at the time the QR code\
\ was scanned."
$ref: "#/definitions/Institution"
thirdPartyIdentifiers:
type: "array"
description: "An array of identifiers which identify the transaction within\
\ each entity's system."
items:
$ref: "#/definitions/ThirdPartyIdentifier"
amounts:
description: "The amounts pertaining to the QR code which was scanned."
$ref: "#/definitions/Amounts"
tranId:
type: "string"
description: "The transaction identifier encoded within the QR Code which\
\ was scanned. Any PaymentRequest with a matching tranId value should be\
\ forwarded to the Partner for processing."
partnerPaymentToken:
type: "string"
description: "A payment token received from the partner in the ScanNotification.\
\ If supplied by the Partner then it will be echoed in the PaymentRequest\
\ to the Partner."
description: "A notification sent by the Partner indicating that the Partner received\
\ a scan of the QR code linked to the transaction ID. Any PaymentRequest with\
\ a matching tranId value should be forwarded to the Partner for processing."
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"
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."
WalletPayment:
allOf:
- $ref: "#/definitions/PaymentMethod"
- type: "object"
required:
- "walletId"
properties:
walletId:
type: "string"
description: "The unique identifier of the wallet account making the payment."
readOnly: true
walletPocket:
description: "The pocket associated with this wallet from which the payment\
\ is to be made. Used to determine where to make a payment from when a\
\ wallet is split into different sections. When not provided, payment\
\ will be directly from the wallet and not a subsection of the wallet."
$ref: "#/definitions/WalletPocket"
description: "Model for mobile wallet payments"
WalletPocket:
type: "object"
required:
- "pocketName"
properties:
pocketName:
type: "string"
description: "The name given to this wallet pocket."
pocketId:
type: "string"
description: "A programmatic ID that can be used to identify this pocket when\
\ the name is not enough"