Borneo Transaction API

9.0.x
(0 reviews)

Requesting Transactions (other than Reversals)

Introduction

This page describes the request and response formats of the POST .../transaction-requests and PUT .../transaction-requests/{requestid} endpoints when used to request _new transactions.

Note: these endpoints are also used to send a reversal request. Reversal requests are described on a separate page.

Request

This chapter outlines the basic elements making up a transaction request.

Transaction Type

Basic Transaction types (txn_type) include:

  • Redemption (aka Purchase)
  • Refund
  • Transfer

The composition of the Payer and the Payee objects (described below) should correspond to the Transaction type provided.

Note: the Reversal transaction type is described on a separate page

Payer and Payee

Since a transaction is an exchange of money from one party to another, we need to be able to identify those two parties.

  • Payer: from where is the money coming

  • Payee: to where is the money going

In the API, both objects take the same form, allowing the following objects to be specified:

  • card

  • account

  • acceptor

Please note that the following objects are mutually exclusive within payer and payee: acceptor, account, card.

Card

Is identified by either a:

  • serial_no; which might for example be known by the requestor if the card was generated over API - or

  • pan; which is the long number on the front of physical cards)

In the PPS data model, a Card exists beneath an Account, so when a Card's details are known and provided, no account should also be provided.

Account

Some transactions are not conducted at the card level, but rather at the level of the account (for example, in consumer banking, money can be sent using a debit card, or by a bank transfer directly from the account).

Accounts can be identified by an:

  • account number (account_no), or

  • external reference number (account_ext_ref) so long as it was provided at the time of creation

When an account is provided, no card should be provided.

Acceptor

The acceptor is usually a merchant selling goods or services. The acceptor's name and id may be provided. These values become metadata on the transaction to help a viewer identify where their money was spent or came from.

Payer/Payee in Redemption transactions:

A purchase of goods from a merchant using a card, means the cardholder is the payer, and the card acceptor (i.e. merchant) is the payee. The following example might be used:

"payer": {
  "card": {
    "pan": "insert-long-card-number-here"
  }
},
"payee": {
  "acceptor": {
    "name": "ACME examples ltd",
    "id": "123456"
  }
}

Payer/Payee in Refund transactions:

When a merchant returns money to a cardholder, since the flow of money is in the other direction, payer and the payee are reversed.

Note: Refunds are distinct transactions and do having any specific relation to a previous transaction. In this way, they are distinct from Reversals, whose affect is to cancel a previous transaction.

Payer/Payee in Transfer transactions:

Transactions can also transfer money from one account holder to another. The following example describes an account identified by 12345678 (the payer) wishing to transfer money to an account identified by 87654321 (the payee).

"payer": {
  "account": {
    "account_no": "12345678"
  }
},
"payee": {
  "account": {
    "account_no": "87654321"
  }
}

Amounts

The Borneo Transaction API communicates amounts as integers accompanied by currency details identifying the currency to use (in ISO-4217 Alpha 3 format, e.g. 'EUR') and the 'exponent' (i.e. the number of decimal places) to apply to the provided amount. The purpose is to guarantee no ambiguity between different systems. As an example, the following object represents the amount €123.45

"requested_amount": {
  "amount": 12345
  "currency": {
    "code": "EUR",
    "exponent": "2"
  }
}

Note: fees that are part of the transaction may also be specified in the fees object. These work in the same vain.

Operation

Debit and Prepaid based products typically have 2 transaction phases:

  • Authorisation: approval for, reservation of, but not finalisation of a transaction.

  • Clearing: finalisation of a transaction.

The operation property in a request indicates the desired phase for the transaction. The Operation AUTH should be used for transactions which have a subsequent clearing phase. The Operation AUTH_AND_CLEAR is reserved for transactions which are considered finished after a successful request.

Credit and Postpaid products can have a 3rd transaction phase:

  • Billing

(see Glossary on front page for more detailed definitions)

Other key identifiers

  • Scheme Service ID: A value provided by PPS as part of the enablement of the interface.
    • Balance Code: Unless your program involves accounts which can have several balances, then use 'MAIN'.

Full example request:

{
  "scheme_service_id": "IATA_EP_ONLINE_AUTH",
  "payee": {
        "acceptor": {
          "name": "name-of-merhcant",
          "id": "id-of-merhcant"
        }
    },
  "payer": {
    "card": {
      "pan": "8842890698518346"
    }
  },
  "operation": "AUTH",
  "txn_type": {
    "code": "REDEMPTION"
  },
  "always_apply": "false",
  "balance_code": "MAIN",
  "requested_amount": {
    "amount": "1000",
    "currency": {
      "code": "SGD",
      "exponent": "2"
    }
  }
}

Response

In the response, many details from the original transaction request are repeated.

This guide will focus only on the values which differ or are new

Transaction identifiers

The following properties provide various means of identifying the transactions

  • id

  • href

  • txn_ids

Note: that the latter two are arrays, because a transaction type can result in more than one transaction. e.g. a transfer results in a 'Transfer Debit' on the sending account, and a 'Transfer Credit' on the receiving account.

A created date/time will also be provided.

Result

The key detail from the response is the result. Possible results are:

  • APPROVEDThe transaction was approved.
  • DECLINEDThe transaction was not approved.In this case, the result_detail will provide further information.
  • APPROVED_WITH_EXCEPTIONThis outcome might apply when a transaction has been forced using the always_apply option to indicate that were the always_apply option not provided, the transaction would not have succeeded. An example would be where the transaction has put the account into a negative state.In this case, the result_detail may provide further information.
  • PARTIALLY_APPROVEDNot all the requested amount was available, but a transaction reserving some of the requested funds has been successfully created, and the requestor should seek payment for the remainder by another means. This outcome is only available when explicitly configured.

Authorisation code

In both the AUTH and AUTH_AND_CLEAR operation modes, a successful transaction request will result in the generation of a value, known as an authorisation code.

Final amount

The final amount applied to the account may be different from the requested amount.

For example, the requested amount may be in a currency that differs from the currency of the affected account. In this case, the transaction processor will automatically apply the appropriate FX rate to result in the final amount.

Another example is when fees are configured on the product which result in a supplement being applied to the requested amount.

Full example response

The following example is a successful result to the transaction reversal request example given above:

{
    "id": "20756069",
    "scheme_service_id": "IATA_EP_ONLINE_AUTH",
    "operation": "AUTH",
    "txn_refs": [
        {
            "href": "/customers/91201/transactions/19022014165137480"
        }
    ],
    "txn_ids": [
        "19022014165137480"
    ],
    "balance_code": "MAIN",
    "auth_code": "026095",
    "requested_amount": {
        "amount": 1000,
        "currency": {
            "code": "SGD",
            "exponent": 2
        }
    },
    "cardholder_final_amount": {
        "amount": 1000,
        "currency": {
            "code": "SGD",
            "exponent": 2
        }
    },
    "payee": {
        "acceptor": {
            "name": "name-of-merchant",
            "id": "id-of-merchant"
        }
    },
    "payer": {
        "card": {
            "pan": "8842890698518346",
            "serial_no": "10000071"
        }
    },
    "result": {
        "result": "APPROVED"
    },
    "created_date_time": "2019-02-20T14:16:51+0000",
    "txn_type": {
        "code": "REDEMPTION"
    }
}

Reviews