Offline Transactions via Deferred Authorizations

To accept card payments, your merchant's POS system must be connected to the internet for processing and authorizing the transaction online. But what happens if the internet connection or the acquirer is down? Usually the merchant is blocked and cannot accept card payments temporarily. This situation can lead, not only to customer dissatisfaction, but also to a real business challenge.
Offline Transactions allow your merchants to accept payments
at their own risk
 when an internet connection is not available. Transactions are queued securely locally and once the internet connection is restored, the merchant can submit the stored Offline Transactions for Deferred Authorization.
Before implementing this feature please talk to your account manager, to understand whether the risk introduced by using Offline Transactions is acceptable for the kind of merchants you aim to serve.
To use Offline Transactions, your POS needs to be extended for running and submitting offline transactions and your processes need to ensure that Offline Transactions are reconciled later on, i.e. that it's verified which transactions got approved or declined in the end.
Running and Submitting Offline Transactions
Starting Offline Transaction
Performing offline transactions is just as simple as performing online transactions:
Implement the
EXECUTE_TRANSACTION_REQUEST
 message as usual, but set the field
mode
 to
OFFLINE
 in the
executeTransactionRequest
: 

    executeTransactionRequest:

{
    "version": "1.1",
    "tag": "a6c40d20-01d7-4b8a-9516-fc56198cea16",
    "type": "EXECUTE_TRANSACTION_REQUEST",
    "resource": "devices/usbReader",
    "executeTransactionRequest": {
        "mode" : "OFFLINE",
        "transactionParameters": {
            "amount": 5.00,
            "currency": "EUR",
            "type": "CHARGE",
            "subject": "My Subject",
            "customIdentifier": "my-custom-identifier"
        }
    }
}
The PayServer responses with
EXECUTE_TRANSACTION_UPDATE
,
EXECUTE_TRANSACTION_ACTION
,
EXECUTE_TRANSACTION_RESPONSE
 messages as defined in the P3 Message Specification. The
EXECUTE_TRANSACTION_RESPONSE
 indicates the transaction execution has completed. 

{
    "tag": "a6c40d20-01d7-4b8a-9516-fc56198cea16",
    "type": "EXECUTE_TRANSACTION_RESPONSE",
    "resource": "devices/usbReader",
    "status": "OK",
    "executeTransactionResponse": {
        "state": "ACCEPTED",
        "stateDetails": "ACCEPTED",
        "transaction": {
            "mode": "OFFLINE",
            "amount": 5.00,
            "currency": "EUR",
            "type": "CHARGE",
            "subject": "My Subject",
            "customIdentifier": "my-custom-identifier",
            "status": "ACCEPTED",
            "merchantReceipt": {
                // ...
            },
            "customerReceipt": {
                // ...
            }
                  // ...
        }
    }
}
In general the transaction execution was successful if the
status
 field in the header is set to
OK
 and the transaction data is present in the body of the response.
But only when the
transaction.status
 equals
ACCEPTED
, is the Offline Transaction was successfully stored for later submission. For any other status, make clear to your merchant that they should not hand out the goods.
You can find more information about the transaction status here.
If there was an error executing the transaction then the
status
 field in the header is set to
ERROR
 and the
error
 object is populated in the response. In error cases the
executeTransactionResponse
 may also be populated with failed final
transaction
 object.
The
merchantReceipt
 and
customerReceipt
 are also present in the response body. Make sure to provide compliant merchant and shopper receipts as documented here.
Refunding Offline Transactions
Refunds for Offline Transactions work in the same way as with online refunds, with the exception that the
mode
 needs to be set to
OFFLINE
 in the
AMEND_TRANSACTION_REQUEST
 message. 

{
    "tag": "bc779b4c-d668-449e-a5d7-d8a42bf3591c",
    "type": "AMEND_TRANSACTION_REQUEST",
    "amendTransactionRequest": {
        "mode": "OFFLINE",
        "transactionParameters": {
            "type": "REFUND",
            "referencedTransactionIdentifier": "97a293ca3b804d639d8552962e0e3522",
            "subject": "My Subject",
            "customIdentifier": "my-custom-identifier"
        }
    }
}
The PayServer responds with
AMEND_TRANSACTION_UPDATE
 and
AMEND_TRANSACTION_RESPONSE
 messages as defined in the P3 Message Specification. The
AMEND_TRANSACTION_RESPONSE
 indicates the transaction execution has completed.

{
    "tag": "bc779b4c-d668-449e-a5d7-d8a42bf3591c",
    "type": "AMEND_TRANSACTION_RESPONSE",
    "resource": "devices/usbReader",
    "status": "OK",
    "amendTransactionResponse": {
        "state": "ACCEPTED",
        "stateDetails": "ACCEPTED",
        "transaction": {
            "mode": "OFFLINE",
            "amount": 5.00,
            "currency": "EUR",
            "type": "CHARGE",
            "subject": "My Subject",
            "customIdentifier": "my-custom-identifier",
            "status": "ACCEPTED",
            "refundDetails": {
                      "status": "REFUNDED",
                      "process": "WITHOUT_CARD",
                      "refundTransactions": [
                                  {
                                      "identifier": "c735ec8ed1794e83882fba8c99ccd7d2",
                                      "createdTimestamp": 1464609191,
                                      "amount": 5.00,
                                      "currency": "EUR",
                                     "type": "REFUND",
                                      "code": "REFUND_BEFORE_CLEARING",
                                      "status": "ACCEPTED",
                                      "statusDetails": {
                                                  "code": "ACCEPTED_WAITING_FOR_SUBMISSION",
                                                  "description": "A description",
                                                 "developerDescription": "A developer description",
                                      }
                                  }
                      ]
                       }
        }
    }
}
You can learn more about how refunds work and how to check the final status here.
Submitting Offline Transactions for Deferred Authorization
Once internet connection is restored, you need to make sure that the merchant submits the stored Offline Transactions for Deferred Authorization: We suggest to train your merchants to do this as part of their daily end-of-day/store closing routines.
Submission is done by implementing the
SUBMIT_TRANSACTIONS_BATCH
 message: Sending the message will submit all stored Offline Transactions to the gateway, which then asynchronously will attempt to run a Deferred Authorization for each of the submitted transactions. 

    
{
    "tag": "1a402d6d-7365-4ef9-a4ea-b609cf69560e",
    "type": "SUBMIT_TRANSACTIONS_BATCH_REQUEST",
    "submitTransactionsBatchRequest": {}
}
If the submission was successful, the
status
 field in the header of
SUBMIT_TRANSACTIONS_BATCH_RESPONSE
 message is set to
OK
. The body of the response will contain a list of submitted transactions.
Note that the returned list of transactions have a different structure from the normal transaction object and contain only minimal information for each submitted transaction. 

{
    "tag": "1a402d6d-7365-4ef9-a4ea-b609cf69560e",
    "type": "SUBMIT_TRANSACTIONS_BATCH_RESPONSE",
    "status": "OK",
    "submitTransactionsBatchResponse": {
         "transactions": [
            {
                "identifier": "31bbff04-d572-4574-9e70-ee2ce6f20eda",
                "statusDetails": {
                        "code": "APPROVED",
                        "description": "APPROVED",
                           "developerDescription": "APPROVED"
                            },
                "refundDetails": {
                        "status": "REFUNDABLE_FULL_ONLY"
            }
        ]
    }
}
If there was an error submitting transactions then the
status
 field in the header is set to
ERROR
 and the standard
error
 object is populated in the response.
In case an error occurs, please make your merchants aware that they need to attempt to submit the Offline Transactions again, until successful.

     {
    "tag": "1a402d6d-7365-4ef9-a4ea-b609cf69560e",
    "type": "SUBMIT_TRANSACTIONS_BATCH_RESPONSE",
    "status": "ERROR",
    "submitTransactionsBatchResponse": {
        "transactions": [
            {
                "identifier": "31bbff04-d572-4574-9e70-ee2ce6f20eda",
                "statusDetails": {
                        "code": "APPROVED",
                        "description": "APPROVED",
                           "developerDescription": "APPROVED"
                            },
                "refundDetails": {
                "status": "REFUNDABLE_FULL_ONLY"
            }
        ]
    }
    "error": {
        "type": "POS_SERVER_ERROR",
        "message":"Error message",
        "developerMessage":"Developer message"
    }
}
In case an error occurs, please make your merchants aware that they need to attempt to submit the Offline Transactions again, until successful.
If the error indicates
POS_SERVER_OFFLINE_BATCH_MALFORMED
 then you will find some submitted transactions to be pending manual review. This indicates that these submitted transactions will be reviewed manually by us because there was some discrepancy with the transaction data.
Lookup and Querying Offline Transactions
Looking up a single Offline Transaction is done with the
GET_TRANSACTION_REQUEST
 message with
mode
 set to
OFFLINE
.

{
    "tag": "32066fb7-6543-4098-816d-04f8241499ac",
    "type": "GET_TRANSACTION_REQUEST",
    "getTransactionRequest": {
        "mode": "OFFLINE",
        "transactionIdentifier": "7e2fc2585cd24f648d96760f56fba26c"
    }
}
Querying transactions can be done with the
QUERY_TRANSACTIONS_REQUEST
 message with the mode set to
sOFFLINE
. 

      {
    "tag": "32066fb7-6543-4098-816d-04f8241499ac",
    "type": "QUERY_TRANSACTIONS_REQUEST",
    "queryTransactionsRequest": {
        "mode": "OFFLINE",
        "filterParameters": {
            "customIdentifier": "my-custom-identifier"
        },
        "includeReceipts": true,
        "offset": 0,
        "limit": 20
    }
}
The respective response messages in either case contain the stored Offline Transactions which were not yet submitted to the gateway.
Reconciling Offline Transactions
After submitting Offline Transactions it's important that you verify the final transaction outcome for each
ACCEPTED
 transaction.
To achieve this, your POS or Backend needs to query each
ACCEPTED
 transaction and then act according to the status:
  • PENDING
     means that the
    ACCEPTED
     transaction is still queued for Deferred Authorization, which will result in either
    APPROVED
     or
    DECLINED
     eventually. You need to check the status again later.
  • APPROVED
     means that the
    ACCEPTED
     transaction has successfully been approved and that the merchant will receive the money. No further actions are required for you and your merchant.
  • DECLINED
     means that the merchant will NOT receive money for the
    ACCEPTED
     transaction. The merchant should either contact the shopper for an alternative method of payment or write off the loss, depending on the payment risk approach of the merchant.
You can get the status of each
ACCEPTED
 transaction by:
  • Querying the your
    TransactionIdentifier
     of the
    ACCEPTED
     transaction from your POS:

{
    "tag": "32066fb7-6543-4098-816d-04f8241499ac",
    "type": "GET_TRANSACTION_REQUEST",
    "getTransactionRequest": {
        "mode": "ONLINE",
        "transactionIdentifier": "yourTransactionIdentifier"
    }
}
  • Receiving a WebHook on your backend with the final status
    APPROVED
     or
    DECLINED
    ) of the transaction. For this you need to match the previously stored
    transactionIdentifier
     of the
    ACCEPTED
     transaction with the
    transactionIdentifier
     of the WebHook.

Related information