API Actions

Payment capture endpoint

Capturing Pre-Authorized Amount

This endpoint is designed to capture the pre-authorized payment amount before an order is processed. It ensures that funds are secured for the order while allowing customers a window of opportunity to cancel, reducing the need for unnecessary refund requests.

Endpoint Usage

• Purpose: Capture the pre-authorized amount for an order.

• When Triggered: Before the order is prepared for processing.

Authorization

• Type: Bearer token

• Required: Yes

• Purpose: Ensures secure access to the API and validates the requester’s identity.

Path Parameters

By implementing this functionality, you enable a smoother customer experience while optimizing API usage by reducing redundant refund operations.

Response Codes for Order Capture Requests

When making an order capture request, the following HTTP response codes are returned to indicate the result of the operation:

• 201 (Created): The request to capture the pre-authorized payment has been successfully processed. This indicates that the order capture was successful and the payment has been secured.

• 403 (Forbidden): The request was denied due to insufficient permissions or invalid authentication. Ensure that the requester has the necessary authorization to perform the capture operation.

• 404 (Not Found): The specified pre-authorized order payment request could not be found. Verify that the orderId is correct and that the order has a valid pre-authorization status before attempting the capture.

These response codes help guide error handling and enable appropriate feedback to users or systems interacting with the order capture process.

Endpoint Details for Capturing Pre-Authorized Payment

To capture the pre-authorized payment for an order, use the POST method on the following endpoint:

/payments/{orderId}/capture

This endpoint is available in both staging and production environments, allowing you to test and deploy the payment capture functionality seamlessly:

• Staging Server: Uses test data for development and testing purposes.

  https://{awsRegionShort}-staging-{brand}-partners-api.rbictg.com/api/v1/payments/{orderId}/capture

• Production Server: Handles live data in the production environment for real transactions.

  https://{awsRegionShort}-prod-{brand}-partners-api.rbictg.com/api/v1/payments/{orderId}/capture

In these URLs, replace {awsRegionShort} with the AWS region abbreviation (e.g., us-east-1) and {brand} with the relevant brand identifier (e.g., popeyes, burgerking).

Ensure to use the appropriate environment for the stage of your project to accurately capture payments and test integrations before going live.

Response Samples for Error Handling

When an error occurs during the payment capture process, the response will return a structured JSON object with relevant details. Below are sample response formats for common error cases:

Sample Response for Error - 403 Forbidden / 404 Not Found

Sample Response Body

Copy code

{ "status": 400, "code": "ValidationError", "message": "isAvailable must be a boolean value", "errors": [{}] }

Explanation of Fields:

• status: Indicates the HTTP status code (e.g., 400 for bad request).

• code: A code representing the specific error type, such as ValidationError.

• message: A brief description of the error. In this case, it's related to an invalid value for isAvailable.

• errors: An array of additional error details, which may provide further information about the validation failure.

This structure helps developers identify and resolve issues efficiently by clearly outlining the cause of the error.

Issue order refund endpoint

There are three ways to issue a refund for a payment that has taken place through our platform:

• Via a specific PSP panel

• Our support admin tool

• Using an order refund endpoint

In this section, we’ll focus on the order refund endpoint.

Please note that by using the aforementioned endpoint does not execute a refund itself but triggers an asynchronous refund request.

Authorization: Bearer and JWT Overview

This API uses the Bearer HTTP authorization scheme to secure endpoints and verify access. Clients must include a valid Bearer token in the Authorization header of each request to protected resources. The Bearer token is formatted as a JSON Web Token (JWT), which is a compact, URL-safe token format designed for securely transmitting claims between parties.

Example Header:

Copy code

Authorization: Bearer <JWT>

The token structure consists of three parts:

1. Header - Specifies the token type (JWT) and the signing algorithm (e.g., HS256 or RS256).

2. Payload - Contains claims such as user identification, roles, and expiration time.

3. Signature - Ensures the token's integrity and authenticity using a secret key or public/private key pair.

This approach simplifies token validation while ensuring secure, stateless communication. Ensure that you handle tokens securely and refresh them as needed to maintain access.

Required Path Parameters

When accessing specific endpoints, the API requires the following path parameter:

• orderId: This is a string that represents a unique RBI order ID. It is mandatory for identifying specific orders in the system.

Request Body Schema

For endpoints requiring a request body, the API accepts the application/json format. The request body must include the following required fields to ensure proper functionality:

Fields

1. issueId (required)

   • Type: string

   • Enum: A predefined set of Issue IDs categorized by support subcategories for specific brands.

   • Example: "6320"

   • Description: Represents the subcategory of the issue related to the request. Each brand has a specific set of Issue IDs.

• Popeyes Issue Categories:

  • Technical issue on app: 7247

  • Technical issue on website: 6685

  • App didn't Load: 7305

Popeyes

• BurgerKing Issue Categories:

  • Technical issue on app: 7313

  • Delivery: 7331

  • Payment: 6319

BurgerKing

• Tim Hortons Issue Categories:

  • Account - Can't Access Email: 7454

  • Loyalty - Lost My Balance: 6865

  • Tim Card - Error Registering to Account: 6864

Tim Hortons

3. primaryReason (required)

   • Type: string

   • Enum:

     • CATERING_ORDER_DECLINED

     • FOOD_QUALITY_ISSUE

     • MISSING_OR_INCORRECT_ITEM

     • OTHER_ADD_COMMENT

     • ...

   • Description: Specifies the reason for attempting the action, such as order refunds.

4. refundMethod (required)

   • Type: string

   • Enum:

     • CUSTOMER: Refund initiated by the customer; logs a note in the support ticket and sends an email to the customer.

     • SUPPORT: Refund executed by the Support Team; logs a note and emails the customer about the refund.

     • AUTO: Refund due to order cancellation; automatically sends an email notification to the customer.

5. requestedAmountCents (required)

   • Type: integer

   • Example: "100" (represents $1.00)

   • Description: Specifies the amount (in cents) to refund as part of the action.

Endpoint Details for Issuing an Order Refund

To issue an order refund, use the POST method on the following endpoint:

/orders/{orderId}/refund

This endpoint is available in both staging and production environments, enabling testing and deployment flexibility:

• Staging Server: Utilizes test data for non-production purposes.

  https://{awsRegionShort}-staging-{brand}-partners-api.rbictg.com/api/v1/orders/{orderId}/refund

• Production Server: Handles live data in a production environment.

  https://{awsRegionShort}-prod-{brand}-partners-api.rbictg.com/api/v1/orders/{orderId}/refund

Replace {awsRegionShort} with the applicable AWS region abbreviation (e.g., us-east-1) and {brand} with the brand identifier (e.g., popeyes or burgerking) to construct the full URL.

Use the appropriate server based on the environment in which you are operating to ensure accurate functionality and data handling.

Request Sample:

Response Sample

403, 404

Response Codes for Order Refund Requests

When handling order refund requests, the API provides the following HTTP response codes to indicate the outcome of the request:

• 201 (Created): Indicates a successful attempt to issue an order refund. The refund process was initiated successfully, and any necessary updates to the system (e.g., customer notifications) have been applied.

• 403 (Forbidden): Indicates that the request was denied due to insufficient permissions or access restrictions. Ensure that the requester has the appropriate authorization to perform this operation.

• 404 (Not Found): Indicates that the specified order could not be found. Verify that the provided orderId is correct and that the order exists in the system.

These response codes should be used to guide error handling and user messaging within the client application.