Payment Flow

Overview

The payment flow remains consistent whether you're utilizing Hosted Checkout or Hosted Session. Below is an outline of the process for authorizing and capturing funds from a payer's account.

The Simplified Payment Flow

  1. Initiate Session to start the payment flow. (required)
  2. Verify the payer's card details and confirm sufficient funds (optional)
  3. Authorize the requested amount. (required)
  4. Capture the funds. (required)

At a basic level, you must always Authorize before Capturing. The Authorization step reserves the funds, and the Capture step debits the funds from the payer's account.

Session Lifecycle

When starting the checkout process for a payer, you will first initiate a session. Sessions are how we handle the payment flow. You will use this session to update the order details, authorize the payment, capture the payment or tokenize the payment source.

Sessions are the starting point and the key to the payment flow. You will need to keep track of the session ID, the order ID and transaction IDs throughout the whole payment flow.

Hosted Checkout or Hosted Session

The payment flow is the same for both Hosted Checkout and Hosted Session.

Hosted Checkout takes much of the burden off the developer by providing a hosted payment page that is PCI compliant. The payer is redirected to the hosted page to enter their payment details and then is returned when the payment is captured.

Hosted Session is a more customizable solution that allows you to build your own payment page. We'll add the hosted payment input fields to your page, and you'll handle the payment flow.

For simplicity, we are going to focus on Hosted Session endpoints.

Initiate

To start the checkout flow, you must always initiate a session.

Starting a session uses the same endpoint for Hosted Checkout or Hosted Session. The difference is in the body of the request and what information you use to handle your order.

Using Hosted Session, you will be handling the payment flow on your own page. In this case, you can update the session with the order details at any time. You will need to eventually authorize the amount you want to charge in order to capture the payment.

Initiate Session Request

POST
merchant/{{merchantId}}/session
No body required

Initiate Session Response

{
  "merchant": "{{merchantId}}",
  "result": "SUCCESS",
  "session": {
    "id": "SESSION0002633418406N6264408G60",
    "updateStatus": "NO_UPDATE",
    "version": "1402556201",
    "aes256Key": "AZnVqk2tSGfrQ+3aaaaamaxkjtRhcFmL4K4aNHROQ/8=",
    "authenticationLimit": 5,
  }
}

Optional Updates

After initiating a session, you can update the session with new information. This is useful if you need to extend the session's validity or adjust the amount.

In the request example, you can see that we are updating the session to have order details. You would do this if you are using Hosted Session.

The orderId must be unique. This is generated by you and sent to us. It is used to identify the order between you and Prahsys.

Request

POST
merchant/{{merchantId}}/session
{
  "order": {
    "id":"{{orderId}}",
    "amount": "100.00",
    "currency": "USD"
  }
}

Response

{
  "merchant": "{{merchantId}}",
  "order": {
    "id": "{{orderId}}",
    "amount": "100.00",
    "currency": "USD",
  },
  "session": {
    "id": "{{sessionId}}",
    "updateStatus": "SUCCESS",
    "version": "926fe64e02"
  },
  "version": "82"
}

The user at this point should have submitted their payment information by using Hosted Session input fields. You can do a couple of things with this session now. You can Tokenize the payment information using the sessionId. You can either Capture the funds or Void the session.

For the sake of this payment flow walkthrough, we will assume that the user has filled out their payment information and you have authorized the order amount. You are ready to capture the payment.

Capture

Once payment authorization is complete, you can proceed to capture the funds, which will debit the payer's account.

Having authorized the payment through the Authorize endpoint, you're now able to capture the payment by using the Capture API.

(Note: If you used Hosted Checkout with the PURCHASE operation, both authorization and capture have already been performed. In this case, you only need to present the receipt.)

The transactionId is a unique identifier that you generate and send to us. It serves as a key reference point for the transaction between your system and Prahsys.

You are responsible for generating this transactionId when interacting with any transaction-related endpoints. It's crucial to maintain a record of this identifier, similar to how you track your orderId.

Request

POST
merchant/{{merchantId}}/order/{{orderId}}/transaction/{{transactionId}}
{
 "apiOperation": "CAPTURE",
 "transaction": {
   "amount": "100.00",
   "currency": "USD"
 }
}

Response

{
    "authorizationResponse": {
        "financialNetworkDate": "0616-01-01",
        "posEntryMode": "123456789012",
        "transactionIdentifier": "BNKNTRF89"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "{{merchantId}}",
    "order": {
        "amount": 100.00,
        "chargeback": {
            "amount": 0,
            "currency": "USD"
        },
        "creationTime": "2024-08-20T22:13:10.728Z",
        "currency": "USD",
        "id": "c22013a0-63da-4ac0-afeb-2ebe46259486",
        "lastUpdatedTime": "2024-08-20T22:13:16.985Z",
        "merchantAmount": 100.00,
        "merchantCategoryCode": "8062",
        "merchantCurrency": "USD",
        "status": "CAPTURED",
        "totalAuthorizedAmount": 100.00,
        "totalCapturedAmount": 100.00,
        "totalDisbursedAmount": 0.00,
        "totalRefundedAmount": 0.00
    },
    "response": {
        "acquirerCode": "",
        "acquirerMessage": "",
        "gatewayCode": "APPROVED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                ...
            }
        },
        "token": "...",
        "type": "SCHEME_TOKEN"
    },
    "timeOfLastUpdate": "2024-08-20T22:13:16.985Z",
    "timeOfRecord": "2024-08-20T22:13:16.647Z",
    "transaction": {
        "acquirer": {
        ...
        },
        ...
        "type": "CAPTURE"
    },
    "version": "82"
}

Refund or Void (Cancel) a Transaction

Refund

If more time has elapsed (typically a day or two) and the funds have been processed, you should initiate a refund instead.

To refund captured funds to the payer:

  1. Provide the original orderId.
  2. Generate a new transactionId.
  3. Specify the refund amount.

You may update other fields as needed, with one crucial exception: do not provide sourceOfFunds.

Refunds are typically linked to the original Capture or Pay transaction through the orderId.

Void

If you've recently called the Capture endpoint and the user wants to cancel their order, you can use the Void endpoint. This action reverses a previous transaction.

Key points about voiding:

  • It's most effective shortly after the original transaction.
  • Success rates decrease as time passes after the initial transaction.