Guides

on-ramp/off-ramp

Suggest Edits

This guide provides detailed instructions for integrating with a payment processing API. It covers essential endpoints for initiating payments, managing payment results, and understanding the type parameter, which specifies the payment processing method.

Understanding the type Parameter

The type parameter is crucial in defining how the payment is processed and determines the method of payment handling. It directs the API on how to process the payment, whether internally within the system, through an external checkout, or via third-party services. The type parameter affects the endpoint’s behavior and the required fields in the request.

Possible Values for type

  • PLATFORM: Indicates that the payment is handled internally within the system. Requires the accountId parameter to specify the internal account for payment processing.

  • CHECKOUT: Signifies that the payment is processed through an external checkout interface, redirecting the user to a payment gateway or external interface. The accountId is not required for this type.

  • EXTERNAL: Used when payments are managed through external third-party systems or services. Includes additional data that might be required by the external system, such as specific integration details or identifiers. The someData field may be required.

Understanding and correctly implementing the type parameter ensures that payment processing aligns with the intended payment method and integrates seamlessly with the chosen payment system.

1. Initiating Payments

1.1 Create or Retrieve Invoice Payment

Create a new payment for an invoice or retrieve details of an existing payment.

Request Parameters

{
  "paymentId": "string",               // Optional: The unique identifier for the payment. Use if retrieving an existing payment.
  "invoiceId": "string",               // Required: The internal identifier of the invoice.
  "discountCode": "string",            // Optional: A discount code to apply to the payment.
  "type": "string",                    // Required: Specifies the payment provider type. 
  "accountId": "string"                // Required for "PLATFORM" type: Internal account identifier for processing payments.
}

1.2 Update Invoice Payment

Update payment details, such as payment method, status, or additional metadata.

Request Parameters

{
  "paymentId": "string",              // Optional: The unique identifier for the payment to be updated.
  "invoiceId": "string",              // Required: The internal identifier of the invoice.
  "discountCode": "string",           // Optional: An optional discount code to apply.
  "type": "string",                   // Required: Indicates the payment provider type. 
  "someData": "string"                // Optional: Additional data relevant to "EXTERNAL" type payments.
}

1.3 Confirm Invoice Payment

Confirm that a payment has been made for an invoice and update its status.

Request Parameters

{
  "paymentId": "string",              // Required: The identifier for the payment to be confirmed.
  "invoiceId": "string",              // Required: The internal identifier of the invoice.
  "discountCode": "string",           // Optional: An optional discount code.
  "type": "string",                   // Required: Defines the payment provider type.
  "accountId": "string",              // Required for "PLATFORM" type: The internal account identifier used for processing.
  "someData": "string"                // Optional: Additional data relevant to "EXTERNAL" type payments.
}

2. Handling Payment Results (Off-Ramp)

2.1 Platform Payment Webhook

Receives notifications about payments processed through the internal platform. Used for updating payment statuses and handling payment-related events.

Request Parameters

{
  "payload": {                       // Contains payment details such as:
    "paymentId": "string",           // The unique identifier for the payment.
    "invoiceId": "string",           // The internal identifier of the invoice.
    "status": "string",              // The current status of the payment.
    "amount": "number",              // The amount of the payment.
    "currency": "string",            // The currency of the payment amount.
    "paymentDate": "number"          // The date of the payment, represented as a timestamp.
  }
}

2.2 External Payment Webhook

Handles notifications for payments processed by external sources. Used to update and manage payment statuses from third-party systems.

Request Parameters

{
  "payload": {                       // Contains payment details such as:
    "paymentId": "string",           // The unique identifier for the payment.
    "invoiceId": "string",           // The internal identifier of the invoice.
    "status": "string",              // The current status of the payment.
    "amount": "number",              // The amount of the payment.
    "currency": "string",            // The currency of the payment amount.
    "paymentDate": "number",         // The date of the payment, represented as a timestamp.
    "externalData": "string"         // Optional: Additional data specific to the external payment system.
  }
}

2.3 Redirect After Successful Checkout

Redirects users to a success page after a payment is completed during checkout.

Request Parameters

{
  "cko-payment-session-id": "string", // Required: Identifier for the payment session.
  "cko-session-id": "string",         // Required: Unique identifier for the checkout session.
  "cko-payment-id": "string"          // Required: Unique payment identifier from the payment gateway.
}

2.4 Redirect After Failed Checkout

Redirects users to an error page if the payment fails during checkout.

Request Parameters

{
  "cko-payment-session-id": "string", // Required: Identifier for the payment session.
  "cko-session-id": "string",         // Required: Unique identifier for the checkout session.
  "cko-payment-id": "string"          // Required: Unique payment identifier from the payment gateway.
}

This guide provides a comprehensive overview of the API endpoints for managing and processing payments, including the detailed role of the type parameter in determining the payment method.

Updated about 2 months ago