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 Giftcard Service Interface Test Server expands upon the\
\ API described in the Electrum
Giftcard Service Interface.
\
\ This expansion does not form part of the core Giftcard Service\
\ Interface but is described here for the
benefit of anyone\
\ making use
of the Giftcard Service Interface Test Server."
version: "1.3.0"
title: "Giftcard Service Interface Test Server"
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: "/giftcard/v3"
tags:
- name: "Activations"
- name: "Confirmations"
- name: "Giftcard Information"
- name: "Loads"
- name: "Redemptions"
- name: "Reversals"
- name: "Test Server Admin"
- name: "Voids"
schemes:
- "https"
paths:
/giftcard/v3/activations/{activationId}:
post:
tags:
- "Activations"
summary: "Request a gift card activation."
description: "The Activations endpoint allows a gift card to be activated. Optionally,\
\ an amount can be included to indicate initial funds which should be credited\
\ to the card. An activation is not considered complete until an activation\
\ confirmation or activation reversal has been sent and acknowledged. An activation\
\ request should only be sent once."
operationId: "activate"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "activationId"
in: "path"
description: "The randomly generated UUID identifying this activation, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The activation information."
required: true
schema:
$ref: "#/definitions/ActivationRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/ActivationResponse"
headers:
Location:
type: "string"
description: "The location of the created activation resource"
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: []
/giftcard/v3/activations/{activationId}/confirmations/{confirmationId}:
post:
tags:
- "Activations"
- "Confirmations"
summary: "Confirm a gift card activation."
description: "The Activation Confirmations endpoint registers the confirmation\
\ of a prior activation of a giftcard. Activation confirmations are advice\
\ type messages and should continue to be sent at suitable intervals until\
\ a response has been received. Multiple confirmation advices may be sent\
\ which refer to the same activation. The net result is that the activation\
\ is confirmed once."
operationId: "confirmActivation"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "activationId"
in: "path"
description: "The randomly generated activationId UUID as sent in the original\
\ activation."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID identifying this confirmation, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The activation confirmation information."
required: true
schema:
$ref: "#/definitions/ActivationConfirmation"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/activations/{activationId}/reversals/{reversalId}:
post:
tags:
- "Activations"
- "Reversals"
summary: "Simplistically, an activation reversal undoes an activation if the\
\ activation was successfully processed."
description: "The Activation Reversals endpoint allows an activation of a giftcard\
\ to be reversed. If the sender of an activation request is uncertain of the\
\ state of an activation request then the sender must send an activation reversal.\
\ Activation reversals are advice type messages and should continue to be\
\ sent at suitable intervals until a response has been received. Multiple\
\ reversals advices may be sent which refer to the same activation. The net\
\ result is that the activation is reversed once."
operationId: "reverseActivation"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "activationId"
in: "path"
description: "The randomly generated activationId UUID as sent in the original\
\ activation."
required: true
type: "string"
- name: "reversalId"
in: "path"
description: "The randomly generated UUID identifying this reversal, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The activation reversal information."
required: true
schema:
$ref: "#/definitions/ActivationReversal"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/loads/{loadId}:
post:
tags:
- "Loads"
summary: "Request funds to be loaded on a gift card."
description: "The Loads endpoint allows loading of funds on a gift card to be\
\ authorized. A load is not considered complete until a load confirmation\
\ or load reversal has been sent and acknowledged. A load request should only\
\ be sent once otherwise multiple loads may occur erroneously."
operationId: "load"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "loadId"
in: "path"
description: "The randomly generated UUID identifying this load, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The load information."
required: true
schema:
$ref: "#/definitions/LoadRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/LoadResponse"
headers:
Location:
type: "string"
description: "The location of the created load resource"
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: []
/giftcard/v3/loads/{loadId}/confirmations/{confirmationId}:
post:
tags:
- "Confirmations"
- "Loads"
summary: "Confirm a load of funds on a gift card."
description: "The Load Confirmations endpoint registers the confirmation of\
\ a prior load on a gift card. Load confirmations are advice type messages\
\ and should continue to be sent at suitable intervals until a response has\
\ been received. Multiple confirmation advices may be sent which refer to\
\ the same load. The net result is that the load is confirmed once."
operationId: "confirmLoad"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "loadId"
in: "path"
description: "The randomly generated loadId UUID as sent in the original load."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID identifying this confirmation, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The load confirmation information."
required: true
schema:
$ref: "#/definitions/LoadConfirmation"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/loads/{loadId}/reversals/{reversalId}:
post:
tags:
- "Loads"
- "Reversals"
summary: "Simplistically, a load reversal undoes a load if the load was successfully\
\ processed."
description: "The Load Reversals endpoint allows loads on a gift card to be\
\ reversed. If the sender of a load request is uncertain of the state of a\
\ load request then the sender must send a load reversal. Reversals should\
\ continue to be sent at suitable intervals until a response has been received.\
\ Multiple reversals may be sent which refer to the same load. The net result\
\ is that the load is reversed once. Note that a load reversal does not equate\
\ to a redemption."
operationId: "reverseLoad"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "loadId"
in: "path"
description: "The randomly generated loadId UUID as sent in the original load."
required: true
type: "string"
- name: "reversalId"
in: "path"
description: "The randomly generated UUID identifying this reversal, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The redemption reversal information."
required: true
schema:
$ref: "#/definitions/LoadReversal"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/lookupGiftcard/{lookupId}:
post:
tags:
- "Giftcard Information"
summary: "Request gift card information."
description: "The Lookup Gift Cards endpoint allows information about a gift\
\ card to be retrieved. This operation has no financial impact and may be\
\ submitted repeatedly without financial consequece. Thus there is no confirmation\
\ or reversal process for gift card lookup requests."
operationId: "lookupGiftcard"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "lookupId"
in: "path"
description: "The randomly generated UUID identifying this lookup request,\
\ as defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "Information describing the gift card lookup to be performed."
required: true
schema:
$ref: "#/definitions/LookupRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/LookupResponse"
headers:
Location:
type: "string"
description: "The location of the gift card lookup resource"
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: []
/giftcard/v3/redemptions/{redemptionId}:
post:
tags:
- "Redemptions"
summary: "Request a redemption of a gift card."
description: "The Redemptions endpoint allows gift cards to be redeemed as a\
\ form of tender. A redemption is not considered complete until a redemption\
\ confirmation or redemption reversal has been sent and acknowledged. A redemption\
\ request should only be sent once otherwise multiple redemptions may occur\
\ erroneously."
operationId: "redeem"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "redemptionId"
in: "path"
description: "The randomly generated UUID identifying this redemption, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The redemption information."
required: true
schema:
$ref: "#/definitions/RedemptionRequest"
responses:
201:
description: "Created"
schema:
$ref: "#/definitions/RedemptionResponse"
headers:
Location:
type: "string"
description: "The location of the created load resource"
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: []
/giftcard/v3/redemptions/{redemptionId}/confirmations/{confirmationId}:
post:
tags:
- "Confirmations"
- "Redemptions"
summary: "Confirm a redemption against a gift card."
description: "The Redemption Confirmations endpoint registers the confirmation\
\ of a prior redemption of a gift card. Redemption confirmations are advice\
\ type messages and should continue to be sent at suitable intervals until\
\ a response has been received. Multiple confirmation advices may be sent\
\ which refer to the same redemption. The net result is that the redemption\
\ is confirmed once."
operationId: "confirmRedemption"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "redemptionId"
in: "path"
description: "The randomly generated redemptionId UUID as sent in the original\
\ redemption."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID identifying this confirmation, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The redemption confirmation information."
required: true
schema:
$ref: "#/definitions/RedemptionConfirmation"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/redemptions/{redemptionId}/reversals/{reversalId}:
post:
tags:
- "Redemptions"
- "Reversals"
summary: "Simplistically, a redemption reversal undoes a redemption if the redemption\
\ was successfully processed."
description: "The Redemption Reversals endpoint allows redemptions on a gift\
\ card to be reversed. If the sender of a redemption request is uncertain\
\ of the state of a redemption request then the sender must send a redemption\
\ reversal. Reversals should continue to be sent at suitable intervals until\
\ a response has been received. Multiple reversals may be sent which refer\
\ to the same redemption. The net result is that the redemption is reversed\
\ once. Note that a reversal does not equate to a load."
operationId: "reverseRedemption"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "redemptionId"
in: "path"
description: "The randomly generated redemptionId UUID as sent in the original\
\ redemption."
required: true
type: "string"
- name: "reversalId"
in: "path"
description: "The randomly generated UUID identifying this reversal, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The redemption reversal information."
required: true
schema:
$ref: "#/definitions/RedemptionReversal"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/testServerAdmin/data:
get:
tags:
- "Test Server Admin"
summary: "Retrieve the test data confirgured in the Giftcard Test Server."
description: "The Test Server Admin Data endpoint allows a user of the Test\
\ Server to retrieve all the card and product data currently configured in\
\ the Test Server. This allows the user to obtain valid card and product information\
\ to use for testing. Note that requests submitted which use cards or products\
\ different from those returned by this operations will not be recognised\
\ by the Test Server and will lead to an error response from the Test Server."
operationId: "data"
consumes:
- "application/json"
produces:
- "application/json"
parameters: []
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/DataResponse"
500:
description: "Internal Server Error"
/giftcard/v3/testServerAdmin/data/card/{cardNumber}:
get:
tags:
- "Test Server Admin"
summary: "Retrieve the test data configured in the Giftcard Test Server for\
\ a certain card."
description: "The Test Server Admin Data endpoint allows a user of the Test\
\ Server to retrieve the card data and state for a card configured in the\
\ Test Server. This allows the user to obtain valid card information to use\
\ for testing as well as the opportunity to examine the state of the card\
\ as it is 'used' in a test."
operationId: "singleCardData"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "cardNumber"
in: "path"
description: "The PAN of the card for which data should be retrieved."
required: true
type: "string"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/DataResponse"
500:
description: "Internal Server Error"
security:
- httpBasic: []
/giftcard/v3/testServerAdmin/data/product/{productId}:
get:
tags:
- "Test Server Admin"
summary: "Retrieve the test data configured in the Giftcard Test Server for\
\ a certain product."
description: "The Test Server Admin Data endpoint allows a user of the Test\
\ Server to retrieve the product data currently configured in the Test Server\
\ for a single specified product. This allows the user to obtain valid product\
\ information to use for testing."
operationId: "singleProductData"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "productId"
in: "path"
description: "The ID of the product for which data should be retrieved."
required: true
type: "string"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/DataResponse"
500:
description: "Internal Server Error"
security:
- httpBasic: []
/giftcard/v3/testServerAdmin/reset:
post:
tags:
- "Test Server Admin"
summary: "Reset the test data in the Giftcard Test Server."
description: "The Test Server Admin Reset endpoint allows a user of the Test\
\ Server to reset the test data in the Test Server's database. This means\
\ that all card and product data will be reset to initial settings and ALL\
\ message data will be lost. This operation affects all data used by the user\
\ identified by the HTTP Basic Auth username and password combination. <em>This\
\ cannot be reversed.</em>"
operationId: "reset"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "The activation confirmation information."
required: true
schema:
$ref: "#/definitions/ResetRequest"
responses:
200:
description: "OK"
schema:
$ref: "#/definitions/ResetResponse"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/ResetResponse"
500:
description: "Internal Server Error"
schema:
$ref: "#/definitions/ResetResponse"
security:
- httpBasic: []
/giftcard/v3/voids/{voidId}:
post:
tags:
- "Voids"
summary: "Request a gift card be voided."
description: "The Voids endpoint allows an activated giftcard to be voided.\
\ A void is not considered complete until a void confirmation or void reversal\
\ has been sent and acknowledged. While a gift card can only be voided once,\
\ a void request should only be sent once and then either confirmed or reversed."
operationId: "voidGiftcard"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "voidId"
in: "path"
description: "The randomly generated UUID identifying this void, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The void information."
required: true
schema:
$ref: "#/definitions/VoidRequest"
responses:
200:
description: "successful operation"
schema:
$ref: "#/definitions/VoidResponse"
201:
description: "Created"
schema:
$ref: "#/definitions/VoidResponse"
headers:
Location:
type: "string"
description: "The location of the created load resource"
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: []
/giftcard/v3/voids/{voidId}/confirmations/{confirmationId}:
post:
tags:
- "Confirmations"
- "Voids"
summary: "Confirm a void of a gift card."
description: "The Void Confirmations endpoint registers the confirmation of\
\ a prior void on a gift card. Void confirmations are advice type messages\
\ and should continue to be sent at suitable intervals until a response has\
\ been received. Multiple confirmation advices may be sent which refer to\
\ the same void. The net result is that the void is confirmed once."
operationId: "confirmVoid"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "voidId"
in: "path"
description: "The randomly generated voidId UUID as sent in the original void."
required: true
type: "string"
- name: "confirmationId"
in: "path"
description: "The randomly generated UUID identifying this confirmation, as\
\ defined for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The void confirmation information."
required: true
schema:
$ref: "#/definitions/VoidConfirmation"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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: []
/giftcard/v3/voids/{voidId}/reversals/{reversalId}:
post:
tags:
- "Voids"
- "Reversals"
summary: "Simplistically, a void reversal undoes a void if the void was successfully\
\ processed."
description: "The Void Reversals endpoint allows voids of a gift card to be\
\ reversed. If the sender of a void request is uncertain of the state of a\
\ void request then the sender must send a void reversal. Reversals should\
\ continue to be sent at suitable intervals until a response has been received.\
\ Multiple reversals may be sent which refer to the same void. The net result\
\ is that the void is reversed once."
operationId: "reverseVoid"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "voidId"
in: "path"
description: "The randomly generated voidId UUID as sent in the original void."
required: true
type: "string"
- name: "reversalId"
in: "path"
description: "The randomly generated UUID identifying this reversal, as defined\
\ for a variant 4 UUID in [RFC 4122](https://tools.ietf.org/html/rfc4122)."
required: true
type: "string"
- in: "body"
name: "body"
description: "The void reversal information."
required: true
schema:
$ref: "#/definitions/VoidReversal"
responses:
202:
description: "Accepted"
schema:
$ref: "#/definitions/BasicAdviceResponse"
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
Originator.Institution.id and\
\ password has been agreed with Electrum."
type: "basic"
definitions:
ActivationConfirmation:
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"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction"
items:
$ref: "#/definitions/Tender"
description: "Information about a gift card activation to be confirmed."
ActivationRequest:
type: "object"
required:
- "card"
- "client"
- "id"
- "originator"
- "product"
- "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"
amounts:
description: "Specifies an amount which should be loaded onto the card as\
\ part of the activation."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being activated."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being activated."
$ref: "#/definitions/Product"
description: "Information about the gift card activation."
ActivationResponse:
type: "object"
required:
- "card"
- "client"
- "id"
- "originator"
- "product"
- "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"
amounts:
description: "Indicates the amount which was requested to be loaded onto the\
\ card during activation, the amount which was loaded and the balance of\
\ the gift card after activation."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being activated."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being activated."
$ref: "#/definitions/Product"
description: "Information about the result of processing the card activation."
ActivationReversal:
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"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "Information about a gift card activation to be reversed."
BasicAdviceResponse:
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"
description: "Basic advice response information."
Basket:
type: "object"
required:
- "basketId"
- "items"
properties:
basketId:
type: "string"
description: "An identifier for the collection of items being paid for."
pattern: "[0-9A-Za-z]{1,20}"
items:
type: "array"
description: "The items being purchased."
items:
$ref: "#/definitions/Item"
description: "Information about the items paid for using the gift card."
Card:
type: "object"
required:
- "expiryDate"
- "pan"
properties:
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}"
clearPin:
type: "string"
description: "The pin number associated with the card unencrypted."
encryptedPin:
type: "string"
description: "The encrypted pin number associated with the card in HEX format."
pattern: "[0-9ABCDEF]+"
description: "Information about a gift card; its number, expiry date and optionally\
\ the PIN either unencrypted or encrypted."
CardData:
type: "object"
required:
- "balance"
- "card"
- "status"
properties:
card:
description: "Card data."
$ref: "#/definitions/Card"
balance:
description: "The balance of the card."
$ref: "#/definitions/LedgerAmount"
status:
type: "string"
description: "The status of the card."
enum:
- "NEW"
- "ACTIVATED"
- "ACTIVATED_CONFIRMED"
- "VOIDED"
- "VOIDED_CONFIRMED"
product:
description: "Product data associated with the card. Only relevant if the\
\ card is activated."
$ref: "#/definitions/Product"
description: "Data about a card stored on the Test Server."
DataResponse:
type: "object"
required:
- "cards"
- "products"
properties:
cards:
type: "array"
description: "The cards configured on the Test Server."
items:
$ref: "#/definitions/CardData"
products:
type: "array"
description: "The products configured on the Test Server."
items:
$ref: "#/definitions/ProductData"
description: "A response to a request to obtain test data from the Test Server."
ErrorDetail:
type: "object"
required:
- "errorMessage"
- "errorType"
- "id"
- "requestType"
properties:
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"
- "INVALID_PRODUCT"
- "CARD_NOT_ACTIVATED"
- "CARD_ACTIVATED"
- "CARD_VOIDED"
- "INSUFFICIENT_FUNDS"
- "INVALID_CARD_NUMBER"
- "CARD_EXPIRED"
- "INCORRECT_PIN"
errorMessage:
type: "string"
description: "A short description of the error"
minLength: 0
maxLength: 20
detailMessage:
type: "object"
description: "A free form detailed description of a particular failure condition\
\ may optionally be supplied"
requestType:
type: "string"
description: "The type of request being processed when the error occurred."
enum:
- "ACTIVATION_CONFIRMATION"
- "ACTIVATION_REQUEST"
- "ACTIVATION_REVERSAL"
- "LOAD_CONFIRMATION"
- "LOAD_REQUEST"
- "LOAD_REVERSAL"
- "LOOKUP_REQUEST"
- "REDEMPTION_CONFIRMATION"
- "REDEMPTION_REQUEST"
- "REDEMPTION_REVERSAL"
- "VOID_CONFIRMATION"
- "VOID_REQUEST"
- "VOID_REVERSAL"
id:
type: "string"
description: "The UUID of the message for which the error occurred."
originalId:
type: "string"
description: "The UUID of the original request message int he case of an error\
\ occurring for an advice message."
description: "Represents the outcome of a completed transaction"
GiftcardAmounts:
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"
availableBalance:
description: "The funds currently available on the card which may be redeemed.\
\ This field should not include loads which must still be finalised."
$ref: "#/definitions/LedgerAmount"
description: "Amounts which make up the transaction. Absent amounts have zero\
\ value."
Institution:
type: "object"
required:
- "id"
- "name"
properties:
id:
type: "string"
description: "The institution's id as assigned by Electrum"
pattern: "[0-9]{1,11}"
name:
type: "string"
description: "The institutions's name"
minLength: 0
maxLength: 40
description: "Originating, acquiring, processing, or receiving institution details"
Item:
type: "object"
properties:
productId:
type: "string"
description: "An identifier for the product such as a barcode."
pattern: "[0-9A-Za-z]{1,20}"
productName:
type: "string"
description: "The name of the product."
pattern: "[0-9A-Za-z]{1,50}"
productType:
type: "string"
description: "The type of the product e.g. food, clothing etc."
pattern: "[0-9A-Za-z]{1,30}"
quantity:
type: "number"
format: "float"
description: "The number of units of product bought. This could be whole units\
\ if suitable for the product (e.g. tins of beans) or a fractional value\
\ in the case of a volume or mass value."
unit:
type: "string"
description: "The unit the quantity is measured in."
enum:
- "UNIT"
- "LITRE"
- "KILOGRAM"
description: "A unique product and quantity thereof which is part of a customer's\
\ basket. This should not be confused with the Product model which describes\
\ a gift card product sold by retailers."
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"
LoadConfirmation:
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"
tenders:
type: "array"
description: "An array of tenders used to pay for the transaction"
items:
$ref: "#/definitions/Tender"
description: "Information about a gift card load to be confirmed."
LoadRequest:
type: "object"
required:
- "amounts"
- "card"
- "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"
amounts:
description: "Specifies an amount which should be loaded onto the card."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being loaded."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being loaded."
$ref: "#/definitions/Product"
description: "Information about the load being made on the gift card."
LoadResponse:
type: "object"
required:
- "amounts"
- "card"
- "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"
amounts:
description: "Indicates the amount which was requested to be loaded onto the\
\ card, the amount which was loaded and the balance of the gift card after\
\ the load."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being loaded."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being loaded."
$ref: "#/definitions/Product"
description: "Information about the load made on the gift card."
LoadReversal:
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"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "Information about the gift card load being reversed."
LookupRequest:
type: "object"
required:
- "card"
- "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"
card:
description: "Information about the gift card being retrieved."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS which captured the card details."
$ref: "#/definitions/PosInfo"
description: "Information about a gift card to be retrieved."
LookupResponse:
type: "object"
required:
- "amounts"
- "card"
- "client"
- "id"
- "originator"
- "posInfo"
- "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"
amounts:
description: "Indicates the balance of the gift card at the time of the request."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card for which information is being\
\ requested."
$ref: "#/definitions/Card"
posInfo:
description: "Information about how card details were captured at the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the product associated with the gift card\
\ if the gift card has been activated."
$ref: "#/definitions/Product"
description: "Information about the result of processing the gift card lookup\
\ request."
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"
pattern: "[a-zA-Z0-9]{8}"
merchant:
description: "Merchant data. Required if available"
$ref: "#/definitions/Merchant"
description: "The Originator object encapsulates data relating to the originator\
\ of the transaction"
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"
description: "POS related data."
Product:
type: "object"
required:
- "id"
properties:
id:
type: "string"
description: "An identifier of the product which the gift card pertains to.\
\ This code is sent by the originator and allows the receiver to identify\
\ the gift card product"
pattern: "[0-9A-Za-z]{1,100}"
barcode:
type: "string"
description: "A barcode code identifying the product the gift card pertains\
\ to."
pattern: "[0-9A-Za-z]{1,13}"
type:
type: "string"
description: "An indication of the type of product offered through the gift\
\ card."
pattern: "[0-9A-Za-z]{1,20}"
description: "Product related data. This is the description of the gift card sold\
\ as a product at a retailer. This should not be confused with the products\
\ which form Items in a Basket."
ProductData:
type: "object"
required:
- "product"
- "startingBalance"
properties:
product:
description: "Product data."
$ref: "#/definitions/Product"
startingBalance:
description: "The starting balance of cards activated against the product."
$ref: "#/definitions/LedgerAmount"
description: "Data about a product stored on the Test Server."
RedemptionConfirmation:
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"
description: "Information about a gift card redemption to be confirmed."
RedemptionRequest:
type: "object"
required:
- "amounts"
- "card"
- "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"
amounts:
description: "Specifies the amount which the gift card is being redeemed against."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being used for redemption."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being used for redemption."
$ref: "#/definitions/Product"
basket:
description: "The collection of products for which the gift card is being\
\ redeemed."
$ref: "#/definitions/Basket"
description: "Information about the redemption being made on the gift card."
RedemptionResponse:
type: "object"
required:
- "card"
- "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"
amounts:
description: "Indicates the amount which the gift card was being redeemed\
\ for, the amount which was redeemed and the balance of the gift card after\
\ redemption."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being redeemed."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being redeemed."
$ref: "#/definitions/Product"
basket:
description: "The collection of products for which the gift card is being\
\ redeemed."
$ref: "#/definitions/Basket"
description: "Information about the redemption made on the gift card."
RedemptionReversal:
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"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "Information about the gift card redemption being reversed."
ResetRequest:
type: "object"
required:
- "resetUserData"
- "userDataWillBeLost"
properties:
userDataWillBeLost:
type: "string"
description: "An acknowledgement that all user data will be lost."
enum:
- "TRUE"
- "FALSE"
resetUserData:
type: "string"
description: "A declaration to reset user data."
enum:
- "TRUE"
- "FALSE"
description: "A request to reset user data in the Test Server."
ResetResponse:
type: "object"
required:
- "outcome"
properties:
outcome:
type: "string"
description: "The outcome of the reset request."
enum:
- "EMPTY_REQUEST"
- "SUCCESSFUL"
- "NO_ACK"
- "NO_DEC"
- "SERVER_ERROR"
- "UNKNOWN_USER"
description: "The outcome of the reset request."
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."
description: "Data that may be printed on the customer slip for information purposes"
SlipLine:
type: "object"
required:
- "text"
properties:
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's ID as assigned by Electrum."
pattern: "[0-9]{1,11}"
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."
VoidConfirmation:
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"
description: "Information about a gift card void to be confirmed."
VoidRequest:
type: "object"
required:
- "card"
- "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"
card:
description: "Information about the gift card being voided."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being voided."
$ref: "#/definitions/Product"
description: "Information about the void of the gift card."
VoidResponse:
type: "object"
required:
- "card"
- "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"
amounts:
description: "Specifies the balance of the gift card when it was voided."
$ref: "#/definitions/GiftcardAmounts"
card:
description: "Information about the gift card being voided."
$ref: "#/definitions/Card"
posInfo:
description: "Information about the POS."
$ref: "#/definitions/PosInfo"
product:
description: "Information about the gift card product being voided."
$ref: "#/definitions/Product"
description: "Information about the outcome of voiding process."
VoidReversal:
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"
reversalReason:
type: "string"
description: "The reason for the reversal"
enum:
- "TIMEOUT"
- "CANCELLED"
- "RESPONSE_NOT_FINAL"
description: "Information about the gift card void being reversed."