QR Payment Service Interface (2.2.0)

The Electrum QR Payment Service describes an interface for supporting payments via scanning of a QR code transactions.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

URL

https://electrum.io

Electrum Support

support@electrum.co.za

Servers

https://docs.electrumsoftware.com/

Schema

Confirms completion of tender initiated by a payment request.

Request

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.

Security

httpBasic

Bodyapplication/jsonrequired

A QR payment confirmation.

idstringrequired

The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122

requestIdstringrequired

The UUID identifying the request that this advice relates to

timestring(date-time)required

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. It is recommended that the optional time-secfrac be included up to millisecond precision

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

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.

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

partnerobject(Institution)

Originating, acquiring, processing, or receiving institution details

tranIdstring or null

An echo of the value in the original PaymentRequest.

curl -i -X POST \
  -u <username>:<password> \
  https://docs.electrumsoftware.com/payments/confirmations \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "requestId": "string",
    "time": "2019-08-24T14:15:22Z",
    "thirdPartyIdentifiers": [
      {
        "institutionId": "string",
        "transactionIdentifier": "string"
      }
    ],
    "stan": "string",
    "rrn": "string",
    "amounts": {
      "requestAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "approvedAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "feeAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "balanceAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "additionalAmounts": {
        "property1": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "property2": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        }
      }
    },
    "partner": {
      "id": "string",
      "name": "string"
    },
    "tranId": "string"
  }'

Responses

Accepted

Bodyapplication/json

idstringrequired

The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122

requestIdstringrequired

The UUID identifying the request that this advice relates to

timestring(date-time)required

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

partnerobject(Institution)

Originating, acquiring, processing, or receiving institution details

tranIdstring or null

An echo of the value in the original PaymentRequest.

Response

application/json

{
  "id": "string",
  "requestId": "string",
  "time": "2019-08-24T14:15:22Z",
  "thirdPartyIdentifiers": [
    { … }
  ],
  "stan": "string",
  "rrn": "string",
  "amounts": {
    "requestAmount": { … },
    "approvedAmount": { … },
    "feeAmount": { … },
    "balanceAmount": { … },
    "additionalAmounts": { … }
  },
  "partner": {
    "id": "string",
    "name": "string"
  },
  "tranId": "string"
}

Requests a payment to be processed via a QR Partner.

Request

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.

Security

httpBasic

Bodyapplication/jsonrequired

A QR payment request.

transactionLabelsArray of objects(TransactionLabel)

A list containing labels that can be used to discover this transaction or group it with other transactions sharing labels with the same label name and value. Transaction labels should never be used to make transaction processing decisions.

idstringrequired

The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122

timestring(date-time)required

originatorobject(Originator)required

The Originator object encapsulates data relating to the originator of the transaction

originator.institutionobject(Institution)required

Originating, acquiring, processing, or receiving institution details

originator.institution.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

originator.institution.namestringrequired

The institutions's name

originator.terminalIdstringrequired

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

originator.merchantobject(Merchant)required

Merchant related data. Must be included if available

originator.merchant.merchantTypestring[0-9]{4}required

The assigned four digit merchant category code

originator.merchant.merchantIdstringrequired

The assigned merchant identifier. Also known as card acceptor id

originator.merchant.merchantNameobject(MerchantName)required

A container object representing the Merchant Name and Location

originator.merchant.merchantName.namestringrequired

The merchant or trading as name associated with the merchant

originator.merchant.merchantName.citystringrequired

The city where the merchant is located

originator.merchant.merchantName.regionstringrequired

The state or region where the merchant is located

originator.merchant.merchantName.countrystringrequired

The country where the merchant is located

originator.operatorIdstring

The ID that uniquely identifies the person operating the terminal specified by the terminalId field.

originator.channelIdstring

The ID that uniquely identifies the originator's channel that this transaction was received through.

clientobject(Institution)required

Originating, acquiring, processing, or receiving institution details

client.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

client.namestringrequired

The institutions's name

settlementEntityobject(Institution)

Originating, acquiring, processing, or receiving institution details

receiverobject(Institution)

Originating, acquiring, processing, or receiving institution details

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

An array of identifiers which each identify the transaction within each entity's system.

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

slipDataobject(SlipData)

Data that may be printed on the customer slip for information purposes

basketRefstring

Used to group multiple transactions which would otherwise be considered independent.

tranTypestring

Indicates the transaction type (i.e. Goods and Services or Cash Withdrawal).

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"

srcAccTypestring

Indicates the type of account being used in a transaction process.

Enum"DEFAULT""SAVINGS""CHEQUE""CREDIT""UNIVERSAL""ELECTRONIC_PURSE""GIFT_CARD""STORED_VALUE"

destAccTypestring

Indicates the type of account being used in a transaction process.

Enum"DEFAULT""SAVINGS""CHEQUE""CREDIT""UNIVERSAL""ELECTRONIC_PURSE""GIFT_CARD""STORED_VALUE"

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

partnerobject(Institution)

Originating, acquiring, processing, or receiving institution details

amountsobject or null(Amounts)required

Amounts which make up the transaction. Absent amounts have zero value.

amounts.requestAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.approvedAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.feeAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.balanceAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.additionalAmountsobject

Any additional amounts that are involved in a transaction which don't appropriately fit into the other amount fields.

tranIdstringrequired

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.

partnerPaymentTokenstring or null

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.

allowedPartnersArray of objects or null(Institution)

A list of partners that are permitted to process this payment. If null or empty, all partners are permitted to process this payment.

curl -i -X POST \
  -u <username>:<password> \
  https://docs.electrumsoftware.com/payments \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionLabels": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "id": "string",
    "time": "2019-08-24T14:15:22Z",
    "originator": {
      "institution": {
        "id": "string",
        "name": "string"
      },
      "terminalId": "string",
      "merchant": {
        "merchantType": "string",
        "merchantId": "string",
        "merchantName": {
          "name": "string",
          "city": "string",
          "region": "string",
          "country": "string"
        }
      },
      "operatorId": "string",
      "channelId": "string"
    },
    "client": {
      "id": "string",
      "name": "string"
    },
    "settlementEntity": {
      "id": "string",
      "name": "string"
    },
    "receiver": {
      "id": "string",
      "name": "string"
    },
    "thirdPartyIdentifiers": [
      {
        "institutionId": "string",
        "transactionIdentifier": "string"
      }
    ],
    "slipData": {
      "messageLines": [
        {
          "barcode": {
            "data": "string",
            "encoding": "string"
          },
          "text": "string",
          "fontWidthScaleFactor": 0.1,
          "fontHeightScaleFactor": 0.1,
          "line": true,
          "cut": true
        }
      ],
      "slipWidth": 0,
      "issuerReference": "string"
    },
    "basketRef": "string",
    "tranType": "GOODS_AND_SERVICES",
    "srcAccType": "DEFAULT",
    "destAccType": "DEFAULT",
    "stan": "string",
    "rrn": "string",
    "partner": {
      "id": "string",
      "name": "string"
    },
    "amounts": {
      "requestAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "approvedAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "feeAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "balanceAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "additionalAmounts": {
        "property1": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "property2": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        }
      }
    },
    "tranId": "string",
    "partnerPaymentToken": "string",
    "allowedPartners": [
      {
        "id": "string",
        "name": "string"
      }
    ]
  }'

Responses

Created

Bodyapplication/json

transactionLabelsArray of objects(TransactionLabel)

idstringrequired

The randomly generated UUID identifying this transaction, as defined for a variant 4 UUID in RFC 4122

timestring(date-time)required

originatorobject(Originator)required

The Originator object encapsulates data relating to the originator of the transaction

originator.institutionobject(Institution)required

Originating, acquiring, processing, or receiving institution details

originator.institution.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

originator.institution.namestringrequired

The institutions's name

originator.terminalIdstringrequired

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

originator.merchantobject(Merchant)required

Merchant related data. Must be included if available

originator.merchant.merchantTypestring[0-9]{4}required

The assigned four digit merchant category code

originator.merchant.merchantIdstringrequired

The assigned merchant identifier. Also known as card acceptor id

originator.merchant.merchantNameobject(MerchantName)required

A container object representing the Merchant Name and Location

originator.merchant.merchantName.namestringrequired

The merchant or trading as name associated with the merchant

originator.merchant.merchantName.citystringrequired

The city where the merchant is located

originator.merchant.merchantName.regionstringrequired

The state or region where the merchant is located

originator.merchant.merchantName.countrystringrequired

The country where the merchant is located

originator.operatorIdstring

The ID that uniquely identifies the person operating the terminal specified by the terminalId field.

originator.channelIdstring

The ID that uniquely identifies the originator's channel that this transaction was received through.

clientobject(Institution)required

Originating, acquiring, processing, or receiving institution details

client.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

client.namestringrequired

The institutions's name

settlementEntityobject(Institution)

Originating, acquiring, processing, or receiving institution details

receiverobject(Institution)

Originating, acquiring, processing, or receiving institution details

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

An array of identifiers which each identify the transaction within each entity's system.

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

slipDataobject(SlipData)

Data that may be printed on the customer slip for information purposes

basketRefstring

Used to group multiple transactions which would otherwise be considered independent.

tranTypestring

Indicates the transaction type (i.e. Goods and Services or Cash Withdrawal).

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"

srcAccTypestring

Indicates the type of account being used in a transaction process.

Enum"DEFAULT""SAVINGS""CHEQUE""CREDIT""UNIVERSAL""ELECTRONIC_PURSE""GIFT_CARD""STORED_VALUE"

destAccTypestring

Indicates the type of account being used in a transaction process.

Enum"DEFAULT""SAVINGS""CHEQUE""CREDIT""UNIVERSAL""ELECTRONIC_PURSE""GIFT_CARD""STORED_VALUE"

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

partnerobject(Institution)required

Originating, acquiring, processing, or receiving institution details

partner.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

partner.namestringrequired

The institutions's name

tendersArray of objects or null or null(Tender)

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.

amountsobject or null(Amounts)required

Amounts which make up the transaction. Absent amounts have zero value.

amounts.requestAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.approvedAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.feeAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.balanceAmountobject(LedgerAmount)

An amount object only containing value and currency, and optionally an indicator of DEBIT/CREDIT

amounts.additionalAmountsobject

Any additional amounts that are involved in a transaction which don't appropriately fit into the other amount fields.

tranIdstringrequired

This value is echoed from the PaymentRequest.

partnerPaymentTokenstring or null

This value is echoed from the PaymentRequest.

allowedPartnersArray of objects or null(Institution)

A list of partners that are permitted to process this payment. If null or empty, all partners are permitted to process this payment.

Response

application/json

{
  "transactionLabels": [
    { … }
  ],
  "id": "string",
  "time": "2019-08-24T14:15:22Z",
  "originator": {
    "institution": { … },
    "terminalId": "string",
    "merchant": { … },
    "operatorId": "string",
    "channelId": "string"
  },
  "client": {
    "id": "string",
    "name": "string"
  },
  "settlementEntity": {
    "id": "string",
    "name": "string"
  },
  "receiver": {
    "id": "string",
    "name": "string"
  },
  "thirdPartyIdentifiers": [
    { … }
  ],
  "slipData": {
    "messageLines": [ … ],
    "slipWidth": 0,
    "issuerReference": "string"
  },
  "basketRef": "string",
  "tranType": "GOODS_AND_SERVICES",
  "srcAccType": "DEFAULT",
  "destAccType": "DEFAULT",
  "stan": "string",
  "rrn": "string",
  "partner": {
    "id": "string",
    "name": "string"
  },
  "tenders": [
    { … }
  ],
  "amounts": {
    "requestAmount": { … },
    "approvedAmount": { … },
    "feeAmount": { … },
    "balanceAmount": { … },
    "additionalAmounts": { … }
  },
  "tranId": "string",
  "partnerPaymentToken": "string",
  "allowedPartners": [
    { … }
  ]
}

Reverses a payment request that failed or timed out

Request

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.

Security

httpBasic

Bodyapplication/jsonrequired

A QR payment reversal.

idstringrequired

The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122

requestIdstringrequired

The UUID identifying the request that this advice relates to

timestring(date-time)required

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

reversalReasonstringrequired

The reason for the reversal

Enum"TIMEOUT""CANCELLED""RESPONSE_NOT_FINAL""REFUND""VOID"

partnerobject(Institution)

Originating, acquiring, processing, or receiving institution details

tranIdstring or null

An echo of the value in the original PaymentRequest.

curl -i -X POST \
  -u <username>:<password> \
  https://docs.electrumsoftware.com/payments/reversals \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "requestId": "string",
    "time": "2019-08-24T14:15:22Z",
    "thirdPartyIdentifiers": [
      {
        "institutionId": "string",
        "transactionIdentifier": "string"
      }
    ],
    "stan": "string",
    "rrn": "string",
    "amounts": {
      "requestAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "approvedAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "feeAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "balanceAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "additionalAmounts": {
        "property1": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "property2": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        }
      }
    },
    "reversalReason": "TIMEOUT",
    "partner": {
      "id": "string",
      "name": "string"
    },
    "tranId": "string"
  }'

Responses

Accepted

Bodyapplication/json

idstringrequired

The randomly generated UUID identifying this advice, as defined for a variant 4 UUID in RFC 4122

requestIdstringrequired

The UUID identifying the request that this advice relates to

timestring(date-time)required

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)required

thirdPartyIdentifiers[].institutionIdstringrequired

The entity's institution ID.

thirdPartyIdentifiers[].transactionIdentifierstringrequired

The identifier assigned to this transaction by the institution represented in institutionId. This value should be unique within the institution's system.

stanstring

The System Trace Audit Number can be used to locate transactions across different systems.

rrnstring

This is a reference set by the original source of the transaction.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

reversalReasonstringrequired

The reason for the reversal

Enum"TIMEOUT""CANCELLED""RESPONSE_NOT_FINAL""REFUND""VOID"

partnerobject(Institution)

Originating, acquiring, processing, or receiving institution details

tranIdstring or null

An echo of the value in the original PaymentRequest.

Response

application/json

{
  "id": "string",
  "requestId": "string",
  "time": "2019-08-24T14:15:22Z",
  "thirdPartyIdentifiers": [
    { … }
  ],
  "stan": "string",
  "rrn": "string",
  "amounts": {
    "requestAmount": { … },
    "approvedAmount": { … },
    "feeAmount": { … },
    "balanceAmount": { … },
    "additionalAmounts": { … }
  },
  "reversalReason": "TIMEOUT",
  "partner": {
    "id": "string",
    "name": "string"
  },
  "tranId": "string"
}

Requests a QR Code to display to a customer to be scanned.

Request

The customer may scan this code with a Partner's application and thereby allow the Partner to identify the QR code provider.

Security

httpBasic

Bodyapplication/jsonrequired

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).

idstringrequired

The randomly generated UUID identifying this request. This may be a variant 3 or 4 as defined in RFC 4122

timestring(date-time)required

originatorobject(Originator)required

The Originator object encapsulates data relating to the originator of the transaction

originator.institutionobject(Institution)required

Originating, acquiring, processing, or receiving institution details

originator.institution.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

originator.institution.namestringrequired

The institutions's name

originator.terminalIdstringrequired

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

originator.merchantobject(Merchant)required

Merchant related data. Must be included if available

originator.merchant.merchantTypestring[0-9]{4}required

The assigned four digit merchant category code

originator.merchant.merchantIdstringrequired

The assigned merchant identifier. Also known as card acceptor id

originator.merchant.merchantNameobject(MerchantName)required

A container object representing the Merchant Name and Location

originator.merchant.merchantName.namestringrequired

The merchant or trading as name associated with the merchant

originator.merchant.merchantName.citystringrequired

The city where the merchant is located

originator.merchant.merchantName.regionstringrequired

The state or region where the merchant is located

originator.merchant.merchantName.countrystringrequired

The country where the merchant is located

originator.operatorIdstring

The ID that uniquely identifies the person operating the terminal specified by the terminalId field.

originator.channelIdstring

The ID that uniquely identifies the originator's channel that this transaction was received through.

clientobject(Institution)required

Originating, acquiring, processing, or receiving institution details

client.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

client.namestringrequired

The institutions's name

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)

An array of identifiers which each identify the transaction within each entity's system.

rrnstring or null

This is a reference set by the original source of the request.

stanstring or null

The System Trace Audit Number can be used to locate transactions across different systems.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

customerobject or null(Customer)

A customer who ultimately requests a transaction be performed.

qrPropertiesobject(QrProperties)

A collection of attributes that describe how a QR code is intended to be used for transacting.

paymentMethodsArray of objects(PaymentMethod)

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.

allowedPartnersArray of objects or null(Institution)

A list of partners that are permitted to process the transaction associated with this QR code. If null or empty, all partners are permitted to process the transaction.

curl -i -X POST \
  -u <username>:<password> \
  https://docs.electrumsoftware.com/qrCodes \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "time": "2019-08-24T14:15:22Z",
    "originator": {
      "institution": {
        "id": "string",
        "name": "string"
      },
      "terminalId": "string",
      "merchant": {
        "merchantType": "string",
        "merchantId": "string",
        "merchantName": {
          "name": "string",
          "city": "string",
          "region": "string",
          "country": "string"
        }
      },
      "operatorId": "string",
      "channelId": "string"
    },
    "client": {
      "id": "string",
      "name": "string"
    },
    "thirdPartyIdentifiers": [
      {
        "institutionId": "string",
        "transactionIdentifier": "string"
      }
    ],
    "rrn": "string",
    "stan": "string",
    "amounts": {
      "requestAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "approvedAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "feeAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "balanceAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "additionalAmounts": {
        "property1": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "property2": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        }
      }
    },
    "customer": {
      "firstName": "string",
      "lastName": "string",
      "address": "string",
      "dateOfBirth": "2019-08-24T14:15:22Z",
      "status": "string",
      "msisdn": "string",
      "emailAddress": "string",
      "addressDetails": {
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "postalCode": "string"
      },
      "profileId": "string"
    },
    "qrProperties": {
      "description": "string",
      "guid": "string",
      "overPaymentAllowed": true,
      "partPaymentAllowed": true,
      "customerProvidedValuePrompts": [
        {
          "label": "string"
        }
      ],
      "requestTip": true,
      "creationDateTime": "2019-08-24T14:15:22Z",
      "expiryDate": "2019-08-24T14:15:22Z",
      "notificationParameters": {
        "recipients": [
          {
            "emailAddress": "string",
            "msisdn": "string"
          }
        ]
      },
      "qrLabel": "string"
    },
    "paymentMethods": [
      {
        "type": "AN_32_TOKEN",
        "name": "string",
        "amount": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "issuer": {
          "id": "string",
          "name": "string"
        },
        "pin": {
          "type": "CLEAR_PIN",
          "pin": "string"
        },
        "proxy": "string",
        "proxyType": "MSISDN",
        "token": "string"
      }
    ],
    "allowedPartners": [
      {
        "id": "string",
        "name": "string"
      }
    ]
  }'

Responses

Created

Bodyapplication/json

idstringrequired

The randomly generated UUID identifying this request. This may be a variant 3 or 4 as defined in RFC 4122

timestring(date-time)required

originatorobject(Originator)required

The Originator object encapsulates data relating to the originator of the transaction

originator.institutionobject(Institution)required

Originating, acquiring, processing, or receiving institution details

originator.institution.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

originator.institution.namestringrequired

The institutions's name

originator.terminalIdstringrequired

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

originator.merchantobject(Merchant)required

Merchant related data. Must be included if available

originator.merchant.merchantTypestring[0-9]{4}required

The assigned four digit merchant category code

originator.merchant.merchantIdstringrequired

The assigned merchant identifier. Also known as card acceptor id

originator.merchant.merchantNameobject(MerchantName)required

A container object representing the Merchant Name and Location

originator.merchant.merchantName.namestringrequired

The merchant or trading as name associated with the merchant

originator.merchant.merchantName.citystringrequired

The city where the merchant is located

originator.merchant.merchantName.regionstringrequired

The state or region where the merchant is located

originator.merchant.merchantName.countrystringrequired

The country where the merchant is located

originator.operatorIdstring

The ID that uniquely identifies the person operating the terminal specified by the terminalId field.

originator.channelIdstring

The ID that uniquely identifies the originator's channel that this transaction was received through.

clientobject(Institution)required

Originating, acquiring, processing, or receiving institution details

client.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

client.namestringrequired

The institutions's name

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)

An array of identifiers which each identify the transaction within each entity's system.

rrnstring or null

This is a reference set by the original source of the request.

stanstring or null

The System Trace Audit Number can be used to locate transactions across different systems.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

customerobject or null(Customer)

A customer who ultimately requests a transaction be performed.

qrPropertiesobject(QrProperties)

A collection of attributes that describe how a QR code is intended to be used for transacting.

paymentMethodsArray of objects(PaymentMethod)

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.

allowedPartnersArray of objects or null(Institution)

A list of partners that are permitted to process the transaction associated with this QR code. If null or empty, all partners are permitted to process the transaction.

tranIdstringrequired

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.

qrCodestringrequired

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.

Response

application/json

{
  "id": "string",
  "time": "2019-08-24T14:15:22Z",
  "originator": {
    "institution": { … },
    "terminalId": "string",
    "merchant": { … },
    "operatorId": "string",
    "channelId": "string"
  },
  "client": {
    "id": "string",
    "name": "string"
  },
  "thirdPartyIdentifiers": [
    { … }
  ],
  "rrn": "string",
  "stan": "string",
  "amounts": {
    "requestAmount": { … },
    "approvedAmount": { … },
    "feeAmount": { … },
    "balanceAmount": { … },
    "additionalAmounts": { … }
  },
  "customer": {
    "firstName": "string",
    "lastName": "string",
    "address": "string",
    "dateOfBirth": "2019-08-24T14:15:22Z",
    "status": "string",
    "msisdn": "string",
    "emailAddress": "string",
    "addressDetails": { … },
    "profileId": "string"
  },
  "qrProperties": {
    "description": "string",
    "guid": "string",
    "overPaymentAllowed": true,
    "partPaymentAllowed": true,
    "customerProvidedValuePrompts": [ … ],
    "requestTip": true,
    "creationDateTime": "2019-08-24T14:15:22Z",
    "expiryDate": "2019-08-24T14:15:22Z",
    "notificationParameters": { … },
    "qrLabel": "string"
  },
  "paymentMethods": [
    { … }
  ],
  "allowedPartners": [
    { … }
  ],
  "tranId": "string",
  "qrCode": "string"
}

Notify that a QR code has been scanned.

Request

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.

Security

httpBasic

Bodyapplication/jsonrequired

A get QR code request.

idstringrequired

The randomly generated UUID identifying this notification. This may be a variant 3 or 4 as defined in RFC 4122

timestring(date-time)required

partnerobject(Institution)required

Originating, acquiring, processing, or receiving institution details

partner.idstringrequired

The institution's ID. API implementations should take care to set this field as appropriate for the implementation.

partner.namestringrequired

The institutions's name

settlementEntityobject(Institution)

Originating, acquiring, processing, or receiving institution details

receiverobject(Institution)

Originating, acquiring, processing, or receiving institution details

thirdPartyIdentifiersArray of objects(ThirdPartyIdentifier)

An array of identifiers which identify the transaction within each entity's system.

amountsobject or null(Amounts)

Amounts which make up the transaction. Absent amounts have zero value.

tranIdstringrequired

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.

partnerPaymentTokenstring or null

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.

curl -i -X POST \
  -u <username>:<password> \
  https://docs.electrumsoftware.com/scans \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "time": "2019-08-24T14:15:22Z",
    "partner": {
      "id": "string",
      "name": "string"
    },
    "settlementEntity": {
      "id": "string",
      "name": "string"
    },
    "receiver": {
      "id": "string",
      "name": "string"
    },
    "thirdPartyIdentifiers": [
      {
        "institutionId": "string",
        "transactionIdentifier": "string"
      }
    ],
    "amounts": {
      "requestAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "approvedAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "feeAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "balanceAmount": {
        "amount": 0,
        "currency": "string",
        "ledgerIndicator": "DEBIT"
      },
      "additionalAmounts": {
        "property1": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        },
        "property2": {
          "amount": 0,
          "currency": "string",
          "ledgerIndicator": "DEBIT"
        }
      }
    },
    "tranId": "string",
    "partnerPaymentToken": "string"
  }'

Responses

Accepted

Response

No content

QR Payment Service Interface (2.2.0)

Schema

Confirms completion of tender initiated by a payment request.

Request

Responses

Was this page helpful?

Requests a payment to be processed via a QR Partner.

Request

Responses

Was this page helpful?

Reverses a payment request that failed or timed out

Request

Responses

Was this page helpful?

Requests a QR Code to display to a customer to be scanned.

Request

Responses

Was this page helpful?

Notify that a QR code has been scanned.

Request

Responses

Was this page helpful?

QR Payment Service Interface (2.2.0)

Schema

Confirms completion of tender initiated by a payment request.

RequestExpand all

Responses

Was this page helpful?

Requests a payment to be processed via a QR Partner.

RequestExpand all

Responses

Was this page helpful?

Reverses a payment request that failed or timed out

RequestExpand all

Responses

Was this page helpful?

Requests a QR Code to display to a customer to be scanned.

RequestExpand all

Responses

Was this page helpful?

Notify that a QR code has been scanned.

RequestExpand all

Responses

Was this page helpful?

Request

Request

Request

Request

Request