xPay

https://docs.xpaycheckout.com
Admin
International payment gateway enabling Indian businesses to accept payments in 30+ currencies across...
Tokens:97,501
Snippets:628
Trust Score:7.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Setup Method

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/get-setup-method

Fetches the details of a specific setup method by its ID. Avoid polling this endpoint; use webhooks for real-time updates.

```APIDOC
## GET /setup-method/{setupMethodId}

### Description
Get details of a setup method

### Method
GET

### Endpoint
https://api.xpaycheckout.com/setup-method/{setupMethodId}

### Parameters
#### Path Parameters
- **setupMethodId** (string) - Required - Unique identifier of the setup method

### Response
#### Success Response (200)
- **setupMethodId** (string) - Unique identifier of the setup method
- **customerId** (string) - The unique identifier for the customer
- **currency** (string) - Three letter abbreviation of the currency
- **paymentMethods** (array) - List of payment methods enabled for setup
- **storeFrontId** (string) - The unique identifier for your storefront
- **callbackUrl** (string) - The URL we will callback to once the setup is complete
- **metadata** (object) - A collection of key-value pairs that were provided when the object was created
- **status** (string) - The status of the setup method
- **pmId** (string) - Unique identifier of the payment method if setup is completed
- **intentId** (string) - Unique identifier of the successful payment intent created while setting up the payment method token.
- **receiptId** (string) - Your identifier for the order.

#### Response Example
{
  "example": "{\n  \"setupMethodId\": \"sm_sK8d3Jq1tZxPjYVhRQW2rf\",\n  \"customerId\": \"cus_Tfd3Jq1tZxPjYVhRQW2r3\",\n  \"currency\": \"USD\",\n  \"paymentMethods\": [\n    \"CARD\",\n    \"GOOGLE_PAY\",\n    \"APPLE_PAY\"\n  ],\n  \"storeFrontId\": \"sf_sK8d3Jq1tZxPjYVhRQW2rf\",\n  \"callbackUrl\": \"https://example.com/callback\",\n  \"metadata\": {\n    \"orderId\": \"12345\",\n    \"customerNote\": \"Setup for recurring payments\"\n  },\n  \"status\": \"CREATED\",\n  \"pmId\": \"pmt_ftoeKIYGC3f43frT\",\n  \"intentId\": \"in_ftoeKIYGC3f43frX\",\n  \"receiptId\": \"recp_123311\"\n}"
}
```

--------------------------------

### OpenAPI Specification for Get Setup Method

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/get-setup-method

This OpenAPI 3.0.1 specification defines the GET /setup-method/{setupMethodId} endpoint. It includes request parameters, response schemas for success (200) and error (400) cases, and component schemas for detailed response structures.

```yaml
GET /setup-method/{setupMethodId}
openapi: 3.0.1
info:
  title: xPay API Store
  description: ''
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.xpaycheckout.com
security:
  - basicAuth: []
paths:
  /setup-method/{setupMethodId}:
    get:
      description: Get details of a setup method
      parameters:
        - name: setupMethodId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the setup method
      responses:
        '200':
          description: Setup Method details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-setup-method-response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    get-setup-method-response:
      type: object
      properties:
        setupMethodId:
          type: string
          description: Unique identifier of the setup method
          example: sm_sK8d3Jq1tZxPjYVhRQW2rf
        customerId:
          type: string
          description: >-
            The unique identifier for the customer, generated via the
            [create-customer API](/api-reference/customers/create-customer)
          example: cus_Tfd3Jq1tZxPjYVhRQW2r3
        currency:
          type: string
          description: Three letter abbreviation of the currency
          example: USD
        paymentMethods:
          type: array
          items:
            type: string
          description: >-
            List of payment methods enabled for setup.


            💡 If a selected payment method is unavailable, the system will
            automatically fallback to card payments to ensure a smooth checkout
            experience.
          example:
            - CARD
            - GOOGLE_PAY
            - APPLE_PAY
        storeFrontId:
          type: string
          description: The unique identifier for your storefront
          example: sf_sK8d3Jq1tZxPjYVhRQW2rf
        callbackUrl:
          type: string
          description: The URL we will callback to once the setup is complete
          example: https://example.com/callback
        metadata:
          type: object
          description: >-
            A collection of key-value pairs that were provided when the object
            was created
          additionalProperties:
            type: string
          example:
            orderId: '12345'
            customerNote: Setup for recurring payments
        status:
          type: string
          description: The status of the setup method
          enum:
            - CREATED
            - SUCCESS
            - FAILED
          example: CREATED
        pmId:
          type: string
          description: Unique identifier of the payment method if setup is completed
          example: pmt_ftoeKIYGC3f43frT
        intentId:
          type: string
          description: >-
            Unique identifier of the successful payment intent created while
            setting up the payment method token. Present only when `amount` is
            passed during setup creation.
          example: in_ftoeKIYGC3f43frX
        receiptId:
          type: string
          description: >-
            Your identifier for the order. Present only when provided during
            setup method creation.
          example: recp_123311
    Error:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          type: string
          example: bad_request
        errorDescription:
          type: string
          example: Failed to read request
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

```

--------------------------------

### Create Setup Method

Source: https://docs.xpaycheckout.com/llms.txt

Create a new setup method for storing payment methods.

```APIDOC
## Create Setup Method

### Description
Create a new setup method for storing payment methods.

### Method
POST

### Endpoint
/setup-methods

### Request Body
- **customerId** (string) - Required - The ID of the customer for whom the payment method is being set up.
- **paymentMethodType** (string) - Required - The type of payment method to set up (e.g., 'card').

### Response
#### Success Response (201 Created)
- **setupMethodId** (string) - The unique identifier for the setup method.
- **customerId** (string) - The ID of the customer.
- **paymentMethodType** (string) - The type of payment method.
```

--------------------------------

### Create Setup Method

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/create-setup-method

Creates a new setup method for storing payment methods. This endpoint allows you to configure the currency, callback URL, and billing details for the payment method setup process.

```APIDOC
## POST /setup-method/create

### Description
Create a new setup method for storing payment methods.

### Method
POST

### Endpoint
https://api.xpaycheckout.com/setup-method/create

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Optional - A unique key for making the request idempotent. Must match pattern: `^[a-zA-Z0-9\-_:\.]+$`.

#### Request Body
- **currency** (string) - Required - Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported).
- **paymentMethods** (array of strings) - Optional - List of payment methods to be enabled for setup. [supported payment methods](/get-started/payment-methods-supported#payment-method-enums).
- **customerId** (string) - Optional - The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer).
- **billingDetails** (object) - Required - Billing details for the customer.
- **storeFrontId** (string) - Optional - The unique identifier for your storefront.
- **callbackUrl** (string) - Required - The URL we will callback to once the setup is complete.
- **metadata** (object) - Optional - A collection of key-value pairs that can be attached to an object for storing additional structured information.
- **phoneNumberRequired** (boolean) - Optional - Flag to indicate whether phone number is required from the customer during checkout. By default, this is false.

### Request Example
```json
{
  "currency": "USD",
  "paymentMethods": [
    "CARD",
    "GOOGLE_PAY",
    "APPLE_PAY"
  ],
  "customerId": "cus_Tfd3Jq1tZxPjYVhRQW2r3",
  "billingDetails": {},
  "storeFrontId": "sf_sK8d3Jq1tZxPjYVhRQW2rf",
  "callbackUrl": "https://example.com/callback",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Setup for recurring payments"
  },
  "phoneNumberRequired": false
}
```

### Response
#### Success Response (200)
- **setupMethodId** (string) - Unique identifier of the setup method.
- **fwdUrl** (string) - The URL to redirect the customer to complete the setup.

#### Response Example
```json
{
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "fwdUrl": "https://pay.xpaycheckout.com/setup-method?id=sm_sK8d3Jq1tZxPjYVhRQW2rf&secret=4b5PyxKSOuunnnFruohoiF"
}
```

#### Error Response (400)
- **errorCode** (string) - Error code.
- **errorDescription** (string) - Description of the error.

#### Error Response Example
```json
{
  "errorCode": "bad_request",
  "errorDescription": "Failed to read request"
}
```
```

--------------------------------

### Create Setup Method

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/create-setup-method

This endpoint allows you to create a new setup method by providing customer details.

```APIDOC
## POST /setup-methods

### Description
Creates a new setup method with the provided customer information.

### Method
POST

### Endpoint
/setup-methods

### Request Body
- **name** (string) - Required - Customer's name
- **email** (string) - Required - Customer's email address
- **contactNumber** (string) - Required - Customer's contact number including country code
- **customerAddress** (object) - Required - Customer's address
  - **country** (string) - Required - Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2))
  - **postalCode** (string) - Required - Postal code

### Request Example
```json
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "contactNumber": "+919123456789",
  "customerAddress": {
    "country": "IN",
    "postalCode": "123456"
  }
}
```

### Response
#### Success Response (200)
- **setupMethodId** (string) - The unique identifier for the created setup method.

#### Response Example
```json
{
  "setupMethodId": "sm_12345abcde"
}
```
```

--------------------------------

### Setup Method Created Event

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/created

This event is triggered when a new setup method is created. It includes details about the event and the newly created setup method.

```APIDOC
## Setup Method Created Event

### Description
This event is triggered when a new setup method is created. It provides information about the event itself and the newly created setup method.

### Event Type
`setup_method.created`

### Event Payload Fields

- **eventId** (string) - Required - A unique identifier for this specific event. This ensures that each event can be tracked and processed individually.
- **eventType** (string) - Required - Describes the type of event. In this case, it signifies that a new setup method has been created.
- **eventTime** (integer) - Required - The timestamp when the event was generated, typically in milliseconds since the Unix epoch (January 1, 1970). This value can be used to track when the event occurred.
- **setupMethodId** (string) - Required - A unique identifier for the specific setup method that was created.
- **receiptId** (string) - Optional - Your identifier for the order. Present only when provided during setup method creation.
- **metadata** (object) - Optional - A collection of key-value pairs that were provided when the setup method was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags.

### Response Example
```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.created",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```
```

--------------------------------

### Create Server-to-Server Setup Method

Source: https://docs.xpaycheckout.com/llms.txt

Create a new setup method for storing payment methods server to server.

```APIDOC
## Create Server-to-Server Setup Method

### Description
Create a new setup method for storing payment methods server to server.

### Method
POST

### Endpoint
/setup-methods/s2s

### Request Body
- **customerId** (string) - Required - The ID of the customer for whom the payment method is being set up.
- **paymentMethodType** (string) - Required - The type of payment method to set up (e.g., 'card').

### Response
#### Success Response (201 Created)
- **setupMethodId** (string) - The unique identifier for the setup method.
- **customerId** (string) - The ID of the customer.
- **paymentMethodType** (string) - The type of payment method.
```

--------------------------------

### Monitor Setup Method Status

Source: https://docs.xpaycheckout.com/products/setup-method/integrationProcess

Use this function to check the current status of a payment method setup. This is useful for verifying if the setup process has completed successfully or if further action is required. It requires the setup method ID to retrieve its status.

```javascript
const getSetupMethodStatus = async (setupMethodId) => {
    const response = await fetch(`/setup-method/${setupMethodId}`);
    return await response.json();
};
```

--------------------------------

### Create Setup Method Request

Source: https://docs.xpaycheckout.com/products/setup-method/integrationProcess

This snippet demonstrates how to initiate a setup method request, which is the first step in securely storing a customer's payment details for future use. It includes setting up the request headers and body with necessary customer and payment information.

```javascript
const createSetupMethod = async (pmId, customerId, amount, currency) => {
    const response = await fetch('/setup-method', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            pmId,
            customerId,
            amount,
            currency
        })
    });
    return await response.json();
};
```

--------------------------------

### setup_method.success Event

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/success

This event is triggered when a setup method is successfully completed. It includes details about the event, the setup method, and associated payment information.

```APIDOC
## setup_method.success Event

### Description
This event is triggered when a setup method is successfully completed. It provides details about the event, the specific setup method, and related payment details.

### Event Fields

- **eventId** (string) - A unique identifier for this specific event. This ensures that each event can be tracked and processed individually.
- **eventType** (string) - Describes the type of event. In this case, it signifies that a setup method has been successfully completed. Value is `setup_method.success`.
- **eventTime** (integer) - The timestamp when the event was generated, typically in milliseconds since the Unix epoch (January 1, 1970). This value can be used to track when the event occurred.
- **setupMethodId** (string) - A unique identifier for the specific setup method that was completed successfully.
- **pmId** (string) - The unique identifier of the payment method that was successfully set up.
- **intentId** (string) - The unique identifier of the payment intent created while setting up the payment method token. Present only when `amount` is passed during setup creation.
- **receiptId** (string) - Your identifier for the order. Present only when provided during setup method creation.
- **metadata** (object) - A collection of key-value pairs that were provided when the setup method was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags.

### Response Example
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.success",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "pmId": "pmt_ftoeKIYGC3f43frT",
  "intentId": "in_ftoeKIYGC3f43frX",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```

--------------------------------

### Create Setup Method OpenAPI Specification

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/create-setup-method

This OpenAPI specification defines the POST /setup-method/create endpoint for creating a new setup method. It includes details on parameters, request body, and responses.

```yaml
POST /setup-method/create
openapi: 3.0.1
info:
  title: xPay API Store
  description: ''
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.xpaycheckout.com
security:
  - basicAuth: []
paths:
  /setup-method/create:
    post:
      description: Create a new setup method for storing payment methods
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: Create Setup Method
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-setup-method'
        required: true
      responses:
        '200':
          description: Setup Method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-setup-method-response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
        pattern: ^[a-zA-Z0-9\-_:\.]+$ 
      description: >-
        A unique key for making the request idempotent. Must match pattern: 
        `^[a-zA-Z0-9\-_:\.]+$`. See [Idempotent
        Requests](/developer-resources/idempotency) for more details.
      example: KG5LxwFBepaKHyUD
  schemas:
    create-setup-method:
      required:
        - currency
        - callbackUrl
        - billingDetails
      type: object
      properties:
        currency:
          type: string
          description: >-
            Three letter abbreviation of the currency. Refer [supported
            currencies](/get-started/currencies-supported)
          example: USD
        paymentMethods:
          type: array
          items:
            type: string
          description: >-
            List of payment methods to be enabled for setup. [supported payment
            methods](/get-started/payment-methods-supported#payment-method-enums)


            💡 If a selected payment method is unavailable, the system will
            automatically fallback to card payments to ensure a smooth checkout
            experience.
          example:
            - CARD
            - GOOGLE_PAY
            - APPLE_PAY
        customerId:
          allOf:
            - $ref: '#/components/schemas/CustomerId'
          description: >-
            The unique identifier for the customer, generated via the
            [create-customer
            API](/developer-resources/endpoints/customer/create-customer).
        billingDetails:
          allOf:
            - $ref: '#/components/schemas/BillingDetails'
          description: Billing details for the customer.
        storeFrontId:
          type: string
          description: The unique identifier for your storefront
          example: sf_sK8d3Jq1tZxPjYVhRQW2rf
        callbackUrl:
          type: string
          description: The URL we will callback to once the setup is complete
          example: https://example.com/callback
        metadata:
          type: object
          description: >-
            A collection of key-value pairs that can be attached to an object
            for storing additional structured information
          additionalProperties:
            type: string
          example:
            orderId: '12345'
            customerNote: Setup for recurring payments
        phoneNumberRequired:
          type: boolean
          description: >-
            Flag to indicate whether phone number is required from the customer
            during checkout. By default, this is false.
          example: false
    create-setup-method-response:
      type: object
      properties:
        setupMethodId:
          type: string
          description: Unique identifier of the setup method
          example: sm_sK8d3Jq1tZxPjYVhRQW2rf
        fwdUrl:
          type: string
          description: The URL to redirect the customer to complete the setup
          example: >-
            https://pay.xpaycheckout.com/setup-method?id=sm_sK8d3Jq1tZxPjYVhRQW2rf&secret=4b5PyxKSOuunnnFruohoiF
    Error:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          type: string
          example: bad_request
        errorDescription:
          type: string
          example: Failed to read request
    CustomerId:
      type: string
      description: >-
        The unique identifier for the customer, generated via the
        [create-customer
        API](/developer-resources/endpoints/customer/create-customer). This can
        be used to associate the payment with a specific customer in your
        system.
      example: cus_Tfd3Jq1tZxPjYVhRQW2r3
    BillingDetails:
      type: object
      description: Billing details for the customer.

```

--------------------------------

### Create S2S Setup Method

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/create-s2s-setup-method

This endpoint is used to initiate the creation of a server-to-server payment setup method. It requires authentication and specific parameters to define the payment details.

```APIDOC
## POST /setup-method

### Description
Initiates the creation of a server-to-server payment setup method.

### Method
POST

### Endpoint
https://pay.xpaycheckout.com/setup-method

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the setup method.
- **secret** (string) - Required - The secret key for authentication.

#### Request Body
- **CustomerId** (string) - Optional - The unique identifier for the customer.
- **CustomerReferenceId** (string) - Optional - Your unique identifier for the customer.
- **BillingDetails** (object) - Optional - Billing details for the customer.
  - **name** (string) - Required - Customer's name.
  - **email** (string) - Required - Customer's email address.
  - **contactNumber** (string) - Required - Customer's contact number including country code.
  - **customerAddress** (object) - Required - Customer's address.
    - **country** (string) - Required - Two-letter country code.
    - **postalCode** (string) - Required - Postal code.
- **CardDetails** (object) - Optional - Payment card information.
  - **cardHolderName** (string) - Optional - Name of the cardholder.
  - **cardNumber** (string) - Required - Full Primary Account Number (PAN).
  - **expiryMonth** (integer) - Required - Card expiry month in MM format.
  - **expiryYear** (integer) - Required - Card expiry year in YY format.
  - **cvv** (string) - Required - Card security code (CVV/CSC).
  - **country** (string) - Optional - Two-letter country code of the card's registered country.
  - **postalCode** (string) - Optional - Postal code of the card's registered location.

### Response
#### Success Response (200)
(Response schema not explicitly defined in the provided text, but would typically include details of the created setup method)

#### Error Response
- **errorCode** (string) - The error code.
- **errorDescription** (string) - A description of the error.

#### Response Example (Error)
{
  "errorCode": "bad_request",
  "errorDescription": "Failed to read request"
}

### Security
- **basicAuth**: Uses HTTP Basic Authentication.
```

--------------------------------

### Setup Method Failed Event Structure

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/failed

This JSON object represents the structure of a setup_method.failed event. It includes details about the event, the failed setup method, and the reason for failure.

```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.failed",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "errorCode": "setup_method_authorisation_failed",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```

--------------------------------

### Redirect to xPay Checkout for Setup

Source: https://docs.xpaycheckout.com/products/setup-method/integrationProcess

Use this JavaScript function to redirect the user to xPay's checkout page for payment method setup. Ensure the fwdUrl is obtained from your server after creating a setup method.

```javascript
const redirectToSetup = () => {
    const url = new URL(fwdUrl); // fwdUrl received from your server after creating a setup method
    window.open(url.href).focus();
};
```

--------------------------------

### Setup Method Created Event Payload

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/created

This JSON payload represents the event triggered when a new setup method is created. It includes event identifiers, timestamps, the ID of the created setup method, and any associated metadata.

```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.created",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```

--------------------------------

### Setup Method Success Event Payload

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/success

This JSON payload represents the structure of the setup_method.success event. It includes details about the event, the setup method, the payment method, and any associated metadata.

```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.success",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "pmId": "pmt_ftoeKIYGC3f43frT",
  "intentId": "in_ftoeKIYGC3f43frX",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```

--------------------------------

### Example Base64 Encoded Credentials

Source: https://docs.xpaycheckout.com/developer-resources/authentication

An example of what a Base64 encoded Authorization header might look like. This string represents the combined username and password.

```http
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
```

--------------------------------

### Payment Intent Creation Timestamp Example

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/payments/list-intents

An example of an epoch timestamp in milliseconds representing when the payment intent was created.

```json
1727340330123
```

--------------------------------

### Setup Method Created Event Structure

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents

This snippet details the structure of the event payload when a new setup method is created. It includes fields like eventId, eventType, eventTime, setupMethodId, and optional metadata.

```APIDOC
## Setup Method Created Event Structure

### Description
This event is triggered when a new setup method is successfully created. It provides details about the event itself and the newly created setup method.

### Event Payload Structure
```json
{
  "eventId": "string",
  "eventType": "setup_method.created",
  "eventTime": "integer",
  "setupMethodId": "string",
  "receiptId": "string" (Optional),
  "metadata": {
    "key": "value"
  } (Optional)
}
```

### Fields
- **eventId** (string) - A unique identifier for this specific event.
- **eventType** (string) - Describes the type of event. For this event, it will be `setup_method.created`.
- **eventTime** (integer) - The timestamp when the event was generated, in milliseconds since the Unix epoch.
- **setupMethodId** (string) - A unique identifier for the specific setup method that was created.
- **receiptId** (string) - Your identifier for the order. Present only when provided during setup method creation.
- **metadata** (object) - A collection of key-value pairs provided during setup method creation. This field is optional.
```

--------------------------------

### Install React Native Dependencies

Source: https://docs.xpaycheckout.com/developer-resources/mobileIntegration

Add the react-native-inappbrowser-reborn library to your React Native project using npm.

```bash
npm install react-native-inappbrowser-reborn
```

--------------------------------

### Get Customer

Source: https://docs.xpaycheckout.com/llms.txt

Get customer details by customer ID.

```APIDOC
## Get Customer

### Description
Get customer details by customer ID.

### Method
GET

### Endpoint
/customer/{customerId}

### Parameters
#### Path Parameters
- **customerId** (string) - Required - The unique identifier of the customer to retrieve.

### Response
#### Success Response (200 OK)
- **customerId** (string) - The unique identifier for the customer.
- **email** (string) - The email address of the customer.
- **firstName** (string) - The first name of the customer.
- **lastName** (string) - The last name of the customer.
- **phone** (string) - The phone number of the customer.
- **createdAt** (string) - The timestamp when the customer was created.
- **updatedAt** (string) - The timestamp when the customer was last updated.
```

--------------------------------

### Get Refund Details

Source: https://docs.xpaycheckout.com/llms.txt

Get details of a single refund by refundId.

```APIDOC
## Get Refund Details

### Description
Get details of a single refund by refundId.

### Method
GET

### Endpoint
/payments/refunds/{refundId}

### Parameters
#### Path Parameters
- **refundId** (string) - Required - The unique identifier of the refund.

### Response
#### Success Response (200 OK)
- **refundId** (string) - The unique identifier for the refund.
- **paymentId** (string) - The ID of the payment that was refunded.
- **amount** (number) - The amount refunded.
- **currency** (string) - The currency of the refund.
- **status** (string) - The status of the refund (e.g., 'succeeded', 'pending').
- **createdAt** (string) - The timestamp when the refund was created.
```

--------------------------------

### POST /setup-method/s2s/create

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/setup-method/create-s2s-setup-method

Creates a new setup method for storing payment methods in a server-to-server integration. This allows for the secure storage of payment details for future transactions.

```APIDOC
## POST /setup-method/s2s/create

### Description
Create a new setup method for storing payment methods server to server.

### Method
POST

### Endpoint
https://api.xpaycheckout.com/setup-method/s2s/create

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Optional - A unique key for making the request idempotent. Must match pattern: `^[a-zA-Z0-9\-_:\.]+$`. See [Idempotent Requests](/developer-resources/idempotency) for more details. Example: KG5LxwFBepaKHyUD

#### Request Body
- **currency** (string) - Required - Three letter abbreviation of the currency. Refer [supported currencies](/get-started/currencies-supported). Example: USD
- **customerId** (string) - Optional - The unique identifier for the customer, generated via the [create-customer API](/developer-resources/endpoints/customer/create-customer). Provide either `customerReferenceId` or this field, not both, as they are mutually exclusive.
- **customerReferenceId** (string) - Optional - Your unique identifier for the customer. Provide either `customerId` or this field, not both, as they are mutually exclusive.
- **billingDetails** (object) - Required - Billing details for the customer.
- **storeFrontId** (string) - Optional - The unique identifier for your storefront. Example: sf_sK8d3Jq1tZxPjYVhRQW2rf
- **callbackUrl** (string) - Required - The URL we will callback to once the setup is complete. Example: https://example.com/callback
- **phoneNumberRequired** (boolean) - Optional - Flag to indicate whether phone number is required from the customer during checkout. By default, this is false. Example: false
- **cardDetails** (object) - Required - Card details for the payment method.
- **amount** (integer) - Optional - The amount to charge immediately while setting up the payment method token. The amount in lowest count unit e.g.: For USD 1, amount is 100 representing 100 cents. Should be greater than 0. Example: 100
- **receiptId** (string) - Optional - Your identifier of the order. This will be persisted in the intent created while setting up the payment method token. Example: order123
- **metadata** (object) - Optional - A collection of key-value pairs that can be attached to an object for storing additional structured information. Maximum of 50 key-value pairs allowed. Each key must be no longer than 40 characters. Each value must be a string and cannot exceed 500 characters. Example: {"orderId": "12345", "customerNote": "Setup for recurring payments"}

### Request Example
```json
{
  "currency": "USD",
  "billingDetails": {},
  "callbackUrl": "https://example.com/callback",
  "cardDetails": {},
  "amount": 100,
  "receiptId": "order123",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Setup for recurring payments"
  }
}
```

### Response
#### Success Response (200)
- **setupMethodId** (string) - Unique identifier of the setup method. Example: sm_sK8d3Jq1tZxPjYVhRQW2rf
- **fwdUrl** (string) - The URL to redirect the customer to complete the setup.

#### Response Example
```json
{
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "fwdUrl": "https://secure.xpaycheckout.com/setup/sm_sK8d3Jq1tZxPjYVhRQW2rf"
}
```

#### Error Response (400)
- **Error** (object) - Details about the invalid request.
```

--------------------------------

### Install Flutter Dependencies

Source: https://docs.xpaycheckout.com/developer-resources/mobileIntegration

Add the necessary packages for in-app web browsing and URL launching to your Flutter project.

```bash
flutter pub add flutter_inappwebview url_launcher
```

--------------------------------

### setup_method.failed Event Structure

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/failed

This event is triggered when a setup method fails. It provides details about the failure, including error codes and associated metadata.

```APIDOC
## setup_method.failed Event

### Description
This event is triggered when a setup method fails. It provides details about the failure, including error codes and associated metadata.

### Event Type
`setup_method.failed`

### Fields
#### eventId (string)
- A unique identifier for this specific event. This ensures that each event can be tracked and processed individually.

#### eventType (string)
- Describes the type of event. In this case, it signifies that a setup method has failed.

#### eventTime (integer)
- The timestamp when the event was generated, typically in milliseconds since the Unix epoch (January 1, 1970). This value can be used to track when the event occurred.

#### setupMethodId (string)
- A unique identifier for the specific setup method that failed.

#### receiptId (string)
- Your identifier for the order. Present only when provided during setup method creation.

#### errorCode (string)
- A specific code indicating the reason for the setup method failure. This helps identify whether the failure was due to user error or processing error. For a complete list of error codes and their meanings, see our [Error Codes](/products/one-time-payments/error-codes) documentation.

#### metadata (object)
- A collection of key-value pairs that were provided when the setup method was created. These metadata values are echoed back in the response, allowing you to store and retrieve custom information such as context-specific attributes, references, or tags.

### Response Example
```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.failed",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "errorCode": "setup_method_authorisation_failed",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```
```

--------------------------------

### Add Flutter Webview Dependencies

Source: https://docs.xpaycheckout.com/developer-resources/mobileIntegration

Install the necessary packages for webview integration and URL launching in Flutter.

```bash
flutter pub add webview_flutter url_launcher
```

--------------------------------

### Create Customer

Source: https://docs.xpaycheckout.com/llms.txt

Create a new customer in the xPay system.

```APIDOC
## Create Customer

### Description
Create a new customer in the xPay system.

### Method
POST

### Endpoint
/customer

### Request Body
- **email** (string) - Required - The email address of the customer.
- **firstName** (string) - Optional - The first name of the customer.
- **lastName** (string) - Optional - The last name of the customer.
- **phone** (string) - Optional - The phone number of the customer.

### Response
#### Success Response (201 Created)
- **customerId** (string) - The unique identifier for the created customer.
- **email** (string) - The email address of the customer.
- **firstName** (string) - The first name of the customer.
- **lastName** (string) - The last name of the customer.
- **phone** (string) - The phone number of the customer.
- **createdAt** (string) - The timestamp when the customer was created.
```

--------------------------------

### Checkout Opened Event Payload

Source: https://docs.xpaycheckout.com/developer-resources/webhooks/events/setupMethodEvents/checkout_opened

This JSON object represents the payload of the setup_method.checkout_opened event. It is triggered when a customer opens a setup method's checkout page and contains details about the event and associated setup method.

```json
{
  "eventId": "whe_fooD944t4VUKkaDT",
  "eventType": "setup_method.checkout_opened",
  "eventTime": 1729608043615,
  "setupMethodId": "sm_sK8d3Jq1tZxPjYVhRQW2rf",
  "receiptId": "order123",
  "metadata": {
    "orderId": "12345",
    "customerNote": "Deliver after 5 PM"
  }
}
```

--------------------------------

### Launch Payment URL in Android Native

Source: https://docs.xpaycheckout.com/developer-resources/mobileIntegration

Configure and launch a Chrome Custom Tab for a payment URL using the AndroidX browser library. This example sets toolbar color and animations.

```kotlin
import androidx.browser.customtabs.CustomTabsIntent
import androidx.browser.customtabs.CustomTabColorSchemeParams
import androidx.core.content.ContextCompat

val customTabsIntent = CustomTabsIntent.Builder()
    .setColorSchemeParams(
        CustomTabColorSchemeParams.Builder()
            .setToolbarColor(ContextCompat.getColor(this, R.color.primary))
            .build()
    )
    .setShowTitle(true)
    .setStartAnimations(this, R.anim.slide_in_right, R.anim.slide_out_left)
    .setExitAnimations(this, R.anim.slide_in_left, R.anim.slide_out_right)
    .build()

// Launch the payment URL in CCT
customTabsIntent.launchUrl(this, Uri.parse(paymentUrl))
```

--------------------------------

### OpenAPI Specification for Get Refunds

Source: https://docs.xpaycheckout.com/developer-resources/endpoints/payments/get-refunds-for-intent

This OpenAPI 3.0.1 specification defines the GET /payments/refunds/{intentId} endpoint. It details the request parameters, including the required intentId, and the structure of successful responses (list of refunds) and error responses.

```yaml
GET /payments/refunds/{intentId}
openapi: 3.0.1
info:
  title: xPay API Store
  description: ''
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.xpaycheckout.com
security:
  - basicAuth: []
paths:
  /payments/refunds/{intentId}:
    get:
      description: Retrieve a list of refunds for a specific payment intent
      parameters:
        - name: intentId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the payment intent
          example: in_fooBOwYsaK50AEfK
      responses:
        '200':
          description: Successful response with list of refunds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-refunds-response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    get-refunds-response:
      type: array
      items:
        $ref: '#/components/schemas/refund-response'
    Error:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          type: string
          example: bad_request
        errorDescription:
          type: string
          example: Failed to read request
    refund-response:
      type: object
      properties:
        refundId:
          type: string
          description: Unique identifier of the refund
          example: rf_fooBOwYsaK50AEaJ
        intentId:
          type: string
          description: Unique identifier of the payment intent
          example: in_fooBOwYsaK50AEfK
        amount:
          $ref: '#/components/schemas/Amount'
        currency:
          $ref: '#/components/schemas/Currency'
        refundedAt:
          $ref: '#/components/schemas/RefundedAt'
        refundReferenceId:
          description: Your identifier for the refund
          type: string
          example: re123
      required:
        - refundId
        - intentId
        - amount
        - currency
        - refundedAt
    Amount:
      type: integer
      format: int64
      description: >-
        The amount in lowest count unit. e.g.: For USD 1, amount is 100
        representing 100 cents (The minimum amount should be greater than 1 USD)
      example: 2000
    Currency:
      type: string
      description: >-
        Three letter abbreviation of the currency. Refer [supported
        currencies](/get-started/currencies-supported)
      example: USD
    RefundedAt:
      type: integer
      format: int64
      description: Epoch timestamp in milliseconds of when the refund was processed
      example: 1727340330123
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

```
Tokens:
Raw