Transactions

Most multi-step API flows, particularly those where money could be exchanged, are ‘wrapped’ in a transaction.

One of the major aims of the transaction feature is to ensure that it is always clear what change you are making to an order and the cost of said change.

A transaction flow will look something like this:

Note that request bodies and much of the responses have been omitted.

Quote

• Quote is used to provide a full summary of the requested change including cost.
• A quote response may indicate various estimates for payment fees (e.g card charges) but these are not exact at this stage

Request: POST /example/quote

Response:

{
    "transaction": {
        "id": "a3759997-310d-4513-8d2a-9e047e58368f",
        "stage": "QUOTE"
    },
    "result": {
        ...
    }
}

• Once async steps have been followed the quote response will include a transaction object.
• The ID from this object must be used in subsequent steps (excluding polling) to progress.

Prepare

• Prepare is used to confirm what payment method (if any) will be used, thus allowing accurate calculation of payment fees (if any).

Request: POST /example/prepare?transactionId=b8c5e73b-ef70-4d5e-bfc2-461fbe853b85

Response:

{
    "transaction": {
        "id": "a3759997-310d-4513-8d2a-9e047e58368f",
        "stage": "PREPARE"
    },
    "result": {
        ...
    }
}

Execute

• Execute is the final step requesting that the change and payment (if applicable) be made

Request: POST /example/execute?transactionId=b8c5e73b-ef70-4d5e-bfc2-461fbe853b85

Response:

{
    "transaction": {
        "id": "a3759997-310d-4513-8d2a-9e047e58368f",
        "stage": "EXECUTE"
    },
    "result": {
        ...
    }
}

Execute response result.status

It is especially important to check result.status for executions.

• SUCCESS - the execution was successful.
  • E.g the bag was added, the order was ticketed, etc
• FAILURE - the execution was not successful.
  • E.g the bag was not added, the order was not ticketed, etc.
• PARTIAL - the execution was partially successful. You will need to resolve this yourself.
  • E.g the old flight was deleted but the new flight wasn’t added, etc.
• UNKNOWN - the execution status (outcome) is unknown. You will need to resolve this yourself.
  • E.g the supplier failed to respond to Paxport

A missing or invalid status field must be treated as UKNOWN.