Overview

Payment Flows

There are two payment flows: two-step and one-step. The flow you need to execute depends on the business process you want to support (note that some payment providers may only support one of the flows):

• In a two-step flow, you first place a hold on the customer’s funds after the payment has been authorized. The next step is known as a capture, in which you complete the transfer to your acquiring bank. This flow is also referred to as Authorize-Capture.

• A one-step flow combines the authorize and capture steps into a single transaction. Funds are transferred from your customer’s account to your acquiring bank once the payment has been authorized. This flow is also known as a Charge.

Operations

Sometimes you’ll need to perform some actions that occur outside a flow. You may need to refund a customer, for instance. Or you may need to cancel an authorization and release the hold on your customer’s funds. These type of actions are known as operations. PaymentsOS supports two types of operations: Void and Refund.

PaymentsOS also allows you to transfer funds from your account directly to your customer, unrelated to any previous customer transaction. This is known as a Credit operation.

Understanding the Payment Object

When accepting your first payment, you may have noticed that the first step in handling the transaction was to create a payment.

Regardless of the payment flow you choose to implement, PaymentsOS requires that you always create a payment object first. The payment object provides a single reference to all the transactions that make up a payment. Whether you already captured the funds or had to refund the customer for (part of) the purchase amount, the payment object will allow you to trace those steps back to the original payment based on the payment id.

Here’s an example of a payment object returned by the Retrieve Payment API. The payment object has references to all related transactions (authorize, capture and refund). Notice that the status object reflects the latest status of the payment, while the related_resources object allows you to backtrace each of the transactions. The possible_next_actions object offers some suggestions as to what to do next.

{
    "id": "f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb",
    "currency": "EUR",
    "created": "1517328109762",
    "modified": "1517328190766",
    "amount": 31602077,
    "status": "Refunded",
    "payment_method": {},
    "related_resources": {
        "authorizations": [
            {
                "href": "https://api.paymentsos.com/payments/f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb/authorizations/e7f819a9-446e-4266-af7a-826339d94510"
            }
        ],
        "captures": [
            {
                "href": "https://api.paymentsos.com/payments/f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb/captures/a3aabc39-94f6-4856-989d-b3bd74a82b45"
            }
        ],
        "refunds": [
            {
                "href": "https://api.paymentsos.com/payments/f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb/refunds/65bf7dbc-9d72-49ae-8778-89610dc8a0d6"
            }
        ]
    },
    "order": {
        "id": "myorderid",
        "tax_percentage": 89099355
    },
    "billing_address": {
        "phone": "aliqua velit tempor"
    },
    "possible_next_actions": [
        {
            "action": "Refund",
            "href": "https://api.paymentsos.com/payments/f7cdc75d-68d3-4a0b-b6ae-39c5a9a2cbcb/refunds"
        }
    ]
}

Payment Status and Transaction Status

You may have noticed the status field in the example above. The status field in the payment object is an overall (composite) status that reflects the status of the payment flow or operation as a whole. If you completed a Capture, for instance, then the payment will have a status of Captured. Learn more about payment and transaction statuses here.

Handling Differences Between Payment Amounts and Authorized Amounts

Some providers allow you to invoke an authorization request for an amount that may be lower or higher than the amount specified in the payment request. For instance, the authorized amount may be lower than the original payment amount if a customer uses loyalty points to pay for a product, or if you attempt to process a payment for which there are not enough funds available in the account to cover the full amount. Likewise, the authorized amount may be higher than the original payment amount if the final transaction amount is not known at the time of payment (for example, fees or commissions may need to be added to the original payment amount).

In the scenarios above, the amount passed in the Create Payment request will differ from the authorized amount returned in the reply of the Create Authorization request. Depending on your business logic, you may want to make sure that your implementation checks whether the amount returned in the response body differs from the original amount and then handle this scenario as required.

Refer to the relevant Provider Integration Guide in the menu on the left for more information per provider.

Interfacing with Multiple Providers

PaymentsOS allows you to define route rules that will allow the PaymentsOS Decision Engine to direct your payments to the most optimal processing destination based on your business needs. This introduces some requirements that you need to be aware of:

• A provider may not necessarily support a specific flow or operation. Bear this in mind when setting up your payment flows.

• Some providers require you to pass in specific data in the API request. Remember that PaymentsOS provides a single API for transacting against multiple providers. You should thus add all the extra data required by your providers to the API requests you invoke.

You can use our bodybuilder to create a request body with all fields required by the providers you are transacting against. For an overview of the requirements specific to each provider, refer to the Provider Integration Guides.