Gateway Merchant API (2.0.0-rc3)

The Gateway Merchant API allows payments from a merchant to any payment processor via an intermediary called a gateway. The gateway abstracts away payment processor specific details allowing the merchant to request transactions from any number of underlying payment processors without separate additional integration between the merchant and the gateway; The gateway itself integrates and abstracts away support for any number of payment processors.

All endpoints of the Merchant API require authentication. The authentication is done via HTTP headers containing a merchant identifier and a signature.

A transfer in or out transaction may have any one of the following values for status:

• success: The transaction was successful; The amount was successfully transferred.
• failure: The transaction has failed; The amount was not and will never be transferred.
• pending: The transaction has been initiated but an amount has not yet been transferred.
• returned: The transaction amount was returned to its origin, for example a chargeback for transfer-in, or a returned Wire for transfer-out.

If a transaction is in a pending state, the merchant may poll the gateway for status updates.

A permanent error is a form of failure; Permanent errors should be returned as a failure status. (at the gateways discretion) A resolvable temporary error may be returned as a pending status when the wallet gateway deems applicable.

In the event of network failures or other issues, preventing communication with the gateway or the gateways ability to reply (Timeouts or 5xx errors) the request should be retried with an exponential backoff strategy and not represent transaction failure.

ONLY a valid reply from the gateway should be considered a transaction status.

With the exception of the /transfer method as this may result in duplicate transactions.

A transfer-in transaction will involve input and processing from at least 4 separate entities: the customer, the cashier, the gateway, and the payment processor. The transfer-in transaction flow between them can be summarized into the following steps:

• The merchant requests a list of payment methods for a user from the gateway
• The merchant displays the payment methods to the customer
• The customer selects a payment method and supplies an amount to deposit
• The payment gateway initiates a transaction and returns transaction information to the cashier.
• The payment gateway may communicate with the payment processor when the payment processor's API expects it; This is abstracted away from the cashier.
• The cashier redirects the customer to the gateway to optionally collect payment details and initiate the transaction via the payment processor. The payment gateway may in turn redirect to the payment processor; this is abstracted away from the cashier.
• The customer is returned to the cashier after the transaction is initiated with the payment gateway and/or payment processor; State may be pending, success, or failure.

After the customer is returned to the cashier, status updates are communicated from the payment gateway to the cashier via callback and polling mechanisms; Callbacks provide real-time status, and polling provides reliability in case of callback failure and precludes the need for a callback retry mechanism.

sequenceDiagram
  participant User
  participant Merchant
  participant Gateway
  User->>Merchant: What can I deposit with?
  Merchant->>+Gateway: Methods Request
  Note over Merchant,Gateway: Merchant would like methods available to user<br/>Methods are only guaranteed valid for 1 transaction
  Gateway->>Merchant: Methods Response
  Merchant->>User: Display methods
  User->>Merchant: I want to deposit with method X
  Note over Merchant,Gateway: A method is selected and a transaction is started      
  Merchant->>Gateway: Transfer Request
  create participant PSP
  Gateway->>PSP: Start Transaction
  PSP->>Gateway: Transaction Info
  Gateway->>-Merchant: Transfer Response
  Note over Merchant,Gateway: The gateway sends the merchant a redirect url<br/>The merchant should redirect the user to this url
  Merchant->>User: Redirect to Url in Transfer Response
  User->>PSP: Attend to the Transaction
  loop Transaction Processing
    Note over Merchant,Gateway: The merchant may request the status at any time
    Merchant-->>Gateway: Status Request
    Gateway-->>Merchant: PENDING
    PSP->>Gateway: Callback with transaction status
    Gateway-->>Merchant: Callback with transaction status SUCCESS
  end
  PSP-->>User: Redirect to return url
  Note over Merchant,Gateway: The user may return at any stage in the transaction<br/>The merchant should be prepared to handle this
  User->>Merchant: Returning to merchant
  Merchant->>User: Display transaction status

The Withdrawal (transfer-out) flow is nearly identical to the Deposit (transfer-in) flow, with the exception that an additional payment approval message sent from the cashier to the gateway.

This is to allow for a payment auditing step; The payment gateway should not send the transaction to the payment processor for processing until the cashier confirms the transaction after auditing.

In addition to the transfer-in transaction flow, the following steps are required at the end of the transfer-in flow documented above:

• The cashier sends a payment approval message to the payment gateway.
• The payment gateway responds with transfer state, pending, success, or failure.

As with the transfer-in flow, transaction status updates are communicated with both callback and polling mechanisms.

sequenceDiagram
  participant User
  participant Merchant
  participant Gateway
  User->>Merchant: What methods are available?
  Merchant->>+Gateway: Methods Request
  Note over Merchant,Gateway: Merchant would like methods available to user<br/>Methods are only guaranteed valid for 1 transaction
  Gateway->>Merchant: Methods Response
  Merchant->>User: Display methods
  User->>Merchant: I want to withdraw with method X
  Note over Merchant,Gateway: A method is selected and a transaction is started      
  Merchant->>Gateway: Transfer Request

  Gateway->>-Merchant: Transfer Response
  Note over Merchant,Gateway: The gateway sends the merchant a redirect url<br/>The merchant should redirect the user to this url
  Merchant->>User: Redirect to Url in Transfer Response
  User->>Gateway: follow redirect
  Note over Merchant,Gateway: The user enters any information required for withdrawal
  Gateway->>User: Display status & redirect to Merchant
  User->>Merchant: Redirect back to merchant
  loop Payment Approval
    Merchant-->>Gateway: Approve Payment
    Gateway-->>Merchant: Transaction Status        
  end
  loop Transaction Processing
    Note over Merchant,Gateway: The merchant may request the status at any time
    Merchant-->>Gateway: Status Request
    Gateway-->>Merchant: PENDING
    PSP->>Gateway: Callback with transaction status
    Gateway-->>Merchant: Callback with transaction status SUCCESS
  end

Useragent should be required for all transfers

• Added user-agent to transfer request as required

Provisions for adding form field support for frontend usage.

• Added formFields to method response
• Added form_fields to transfer request