IATA EasyPay integration API

Introduction

This page describes how the POST /iepns endpoint is used to generate an IEPN for use in a purchase.

Wallet allocation

In order to generate an IEPN, EasyPay needs to identify a wallet from from which to do the generation. Whilst an integrated party is surely aware of the IATA Codes and Currencies for which they wish to make purchases, since Agencies can have multiple open wallets, the IATA Code and Currency is not necessarily sufficient.

The EasyPay Portal can be used to set and view wallet names, as well as to see wallet ids. Wallet names which uniquely identify a wallet within an IEP Account, and wallet ids can both be used by integrated parties in requests to generate IEPNs.

Alternatively, Integrated parties may omit wallet identifiers in IEPN generation requests and EasyPay will apply a simple process to identify a suitable wallet from which to issue. This process is as described:

Even though a wallet was not identified in an IEPN generation request, requests for agencies in scenarios 1 and 2 will result in a predictable selection of a wallet.

Other validations

Once a candidate wallet has been identified, whether as part of the request, or derived from the defaulting procedure described above, its allocation alone is not sufficient to go ahead and issue an IEPN. The following validations must also take place:

1. The Wallet must be in an Open state (necessarily satisfied for wallets selected by the defaulting procedure)
2. The Currency specified in the request matches the currency of the wallet (necessarily satisfied for wallets selected by the defaulting procedure)
3. The Agency specified must be in an Approved state
4. The IEP Account hosting the Agency must be in an Open state
5. The Wallet must have a positive balance
6. (The wallet's balance may additionally need to greater than or equal to an amount specified in the request. See maximum_purchase_amount and validate_wallet_balance)

Purchases and Amounts

IEPNs:

• have an expiry date of the end of the month that follows the month in which it was generated. Authorisation requests after the expiry date will be declined.
• may only be used for a single purchase. After successfully accepting an authorisation request, an IEPN can no longer be used to make purchases, even if the original authorisation is reversed or refunded.
• are by default not tied to a specific value. The IEPN could be used to make any purchase up to the amount of the balance in the wallet at the time the IEPN is used in an authorisation (as opposed to the balance at the time of generation)

Optionally, the caller may specify in an IEPN generation request a maximum_purchase_amount. When this is specified, the IEPN may be used to make purchases up to the lower of the maximum_purchase_amount and the balance of the IEPNs wallet at the point of authorisation. By default, EasyPay will not compare maximum_purchase_amount against the wallet balance at the point of generation.

Optionally, the caller may additionally set in an IEPN generation request the query parameter validate_wallet_balance to true. This will force EasyPay to compare the maximum_purchase_amount to the wallet balance at the point of generation and proceed to issue the IEPN only where the balance available is equal to or greater than the maximum_purchase_amount.

Please note: Neither maximum_purchase_amount nor validate_wallet_balance have any impact on the wallet allocation defaulting behaviour described above.

Example Request/Responses

Sample Data

The examples on this page use the agency and wallet data below as a point of reference in order to demonstrate the various scenarios that may arise:

IEP Account 1 : Status: Open

IEP Account 2 : Status: Closed

Success Examples

Success Example 1. Selection of directly funded wallet by default

Request: POST /iepns

{
  "iata_code": "11111111",
  "currency": "EUR"
}

Response: 201

{
  "serial_no": "1000023456",
  "iepn": "5164700012345678",
  "iata_code": "11111111",
  "expiry_date": "2018-09-30T23:59:59Z",
  "wallet": {
    "id": "63a3a442-670a-4df4-9573-80d3661f4e8a",
    "name": "my-wallet-name",
    "allocation": "DEFAULTED_TO_DIRECTLY_FUNDED_WALLET"
  }
  "currency": "EUR"
}

Success Example 2. Selection of lone indirectly funded wallet by default

Request: POST /iepns

{
  "iata_code": "22222222",
  "currency": "EUR"
}

Response: 201

{
  "serial_no": "1000023456",
  "iepn": "5164700012345678",
  "iata_code": "22222222",
  "expiry_date": "2018-09-30T23:59:59Z",
  "wallet": {
    "id": "73b1fec0-53ba-42c9-b113-d5b71d2eaf49",
    "name": "my-wallet-name",
    "allocation": "DEFAULTED_TO_LONE_INDIRECTLY_FUNDED_WALLET"
  }
  "currency": "EUR"
}

Success Example 3. Selection of any wallet explicitly

Request: POST /iepns

{
  "iata_code": "11111111",
  "currency": "EUR",
  "wallet": {
    "id": "9c2d04ea-1980-4cd2-ab89-7128611fbd3a"
  }
}

Response: 201

{
  "serial_no": "1000023456",
  "iepn": "5164700012345678",
  "iata_code": "11111111",
  "expiry_date": "2018-09-30T23:59:59Z",
  "wallet": {
    "id": "9c2d04ea-1980-4cd2-ab89-7128611fbd3a",
    "name": "my-wallet-name",
    "allocation": "SPECIFIED_IN_REQUEST"
  }
  "currency": "EUR"
}

Success Example 4. Example 2 with a maximum_purchase_amount which does not get validated against the wallet balance

Request: POST /iepns

{
  "iata_code": "22222222",
  "currency": "EUR",
  "maximum_purchase_amount": 20000
}

Response: 201

{
  "serial_no": "1000023456",
  "iepn": "5164700012345678",
  "iata_code": "22222222",
  "expiry_date": "2018-09-30T23:59:59Z",
  "wallet": {
    "id": "73b1fec0-53ba-42c9-b113-d5b71d2eaf49",
    "name": "my-wallet-name",
    "allocation": "DEFAULTED_TO_LONE_INDIRECTLY_FUNDED_WALLET"
  }
  "currency": "EUR",
  "maximum_purchase_amount": 20000
}

Success Example 5. Example 2 with a maximum_purchase_amount successfully validated against the wallet balance

Request: POST /iepns?validate_wallet_balance=true

{
  "iata_code": "22222222",
  "currency": "EUR",
  "maximum_purchase_amount": 8000
}

Response: 201

{
  "serial_no": "1000023456",
  "iepn": "5164700012345678",
  "iata_code": "22222222",
  "expiry_date": "2018-09-30T23:59:59Z",
  "wallet": {
    "id": "73b1fec0-53ba-42c9-b113-d5b71d2eaf49",
    "name": "my-wallet-name",
    "allocation": "DEFAULTED_TO_LONE_INDIRECTLY_FUNDED_WALLET"
  }
  "currency": "EUR",
  "maximum_purchase_amount": 20000
}

Failure Examples

Failure Example 1. Currency mismatch

Request: POST /iepns

{
  "iata_code": "11111111",
  "currency": "USD",
  "wallet": {
    "id": "63a3a442-670a-4df4-9573-80d3661f4e8a"
  }
}

Response: 422

{
  "status": "422",
  "message": "Invalid currency",
  "detail": "The currency provided does not match the currency of the wallet specified. Wallet Currency: EUR"
}

Failure Example 2. Specified Wallet is closed

Request: POST /iepns

{
  "iata_code": "22222222",
  "currency": "EUR",
  "wallet": {
    "id": "f0d1a4bf-91be-41ff-8d35-9ad0917856a7"
  }
}

Response: 422

{
  "status": "422",
  "message": "Invalid wallet",
  "detail": "The specified wallet is not in an appropriate state. Wallet status: CLOSED"
}

Failure Example 3. Specified iata code in invalid state

Request: POST /iepns

{
  "iata_code": "55555555",
  "currency": "EUR"
}

Response: 422

{
  "status": "422",
  "message": "Invalid agency",
  "detail": "The agency specified is not in an appropriate state. Agency status: TERMINATED"
}

Failure Example 4. IEP Account hosting specified iata code in invalid state

Request: POST /iepns

{
  "iata_code": "99999999",
  "currency": "EUR"
}

Response: 422

{
  "status": "422",
  "message": "Invalid IEP Account state",
  "detail": "The status of the IEP Account hosting the agency specified is not in an appropriate state. IEP Account status: CLOSED"
}

Failure Example 5. Specified wallet has 0 balance

Request: POST /iepns

{
  "iata_code": "33333333",
  "currency": "EUR",
  "wallet": {
    "id": "a44f0c1a-16d2-4ab4-b3b5-efe326b63ddd"
  }
}

Response: 422

{
  "status": "422",
  "message": "Insufficient funds",
  "detail": "The wallet identified either in the request or by defaulting behaviour does not have sufficient funds for the purchase. Wallet balance: 0.00 EUR"
}

Failure Example 6. Success Example 2 with a maximum_purchase_amount unsuccessfully validated against the wallet balance

Request: POST /iepns?validate_wallet_balance=true

{
  "iata_code": "22222222",
  "currency": "EUR",
  "maximum_purchase_amount": 20000
}

Response: 422

{
  "status": "422",
  "message": "Insufficient funds",
  "detail": "The wallet identified either in the request or by defaulting behaviour does not have sufficient funds for the purchase. Wallet balance: 100.00 EUR"
}

Failure Examples 7, 8, 9, 10, 11. Rejection due to unable to find suitable wallet
Example 7

Request: POST /iepns

{
  "iata_code": "00000000",
  "currency": "EUR"
}

Response: 400

{
  "status": "400",
  "message": "Wallet selection not possible",
  "detail": "A wallet was neither identified in the request nor identifiable by defaulting behaviour"
}

Example 8
Request: POST /iepns

{
  "iata_code": "22222222",
  "currency": "USD"
}

Response: 400

{
  "status": "400",
  "message": "Wallet selection not possible",
  "detail": "A wallet was neither identified in the request nor identifiable by defaulting behaviour"
}

Example 9
Request: POST /iepns

{
  "iata_code": "33333333",
  "currency": "EUR"
}

Response: 400

{
  "status": "400",
  "message": "Wallet selection not possible",
  "detail": "A wallet was neither identified in the request nor identifiable by defaulting behaviour"
}

Example 10
Request: POST /iepns

{
  "iata_code": "44444444",
  "currency": "EUR"
}

Response: 400

{
  "status": "400",
  "message": "Wallet selection not possible",
  "detail": "A wallet was neither identified in the request nor identifiable by defaulting behaviour"
}

Example 11

Request: POST /iepns

{
  "iata_code": "11111111",
  "currency": "EUR",
  "wallet": {
    "id": "thiswall-etdo-esno-texi-stthiswallet"
  }
}

Response: 400

{
  "status": "400",
  "message": "Wallet selection not possible",
  "detail": "A wallet was neither identified in the request nor identifiable by defaulting behaviour"
}