Payment

Overview

This document outlines how to initiate transactions using the Facilero Alternative Payment Methods (APM) API. The API supports various payment methods such as e-wallets, mobile wallets, bank transfers, and more. By using the provided endpoints, you can process payments and receive callbacks with transaction details.

API Endpoint

Live

POST https://api.facilero.com/api/v1/payments/apm

Sandbox

POST https://sandbox.facilero.com/api/v1/payments/apm

Request Headers

• Content-Type: application/json
• Authorization: Bearer <AUTH_TOKEN> - Replace <AUTH_TOKEN> with the actual token obtained from the Authorization Service.
• Referer: <REFERER_URL> - Replace <REFERER_URL> with the relevant referring URL.

Request Body

Fields

ApmBillingDetails Object

Note: Fields marked with No* are not required by default, but may be required for specific payment methods. Please consult the APM-specific documentation to determine which fields are required for your chosen payment method.

Device Object

Note: Fields marked with No* are not required by default, but may be required for specific payment methods. Please consult the APM-specific documentation to determine which fields are required for your chosen payment method.

Order Object

Note: Fields marked with No* are not required by default, but may be required for specific payment methods. Please consult the APM-specific documentation to determine which fields are required for your chosen payment method.

Response

Response Object

ApmResponseData Object

The apmResponseData field contains payment method-specific response data necessary for completing the payment flow:

Note: Different payment methods might have additional fields specific to their implementation.

Callback

After processing, the transaction result will be sent to the callbackUrl specified in the request. The callback uses the ApmPaymentTxInfoDto object format with the following structure.

In addition, Facilero includes a checksum header to ensure callback authenticity. See the Checksum Authentication Guide for details.

Callback Headers

Callback Data Object (ApmPaymentTxInfoDto)

Example Request (ExPay E-Wallet)

{
  "requestId": "req-123456789",
  "accountId": "12345",
  "apmPayload": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    // Additional ExPay-specific fields
  },
  "amount": "100.00",
  "currency": "USD",
  "callbackUrl": "https://merchant.example.com/callbacks/payments",
  "billingDetails": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "postalCode": "10001"
  },
  "order": {
    "orderId": "order-123456",
    "description": "Payment for services",
    "items": [
      {
        "name": "Service A",
        "quantity": 1,
        "price": "100.00"
      }
    ]
  },
  "metadata": {
    "customField1": "value1",
    "customField2": "value2"
  }
}

Example Response

{
  "requestId": "req-123456789",
  "transactionId": "tx-987654321",
  "transactionStatus": "PENDING",
  "apmResponseData": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "redirectUrl": "https://pay.ExPay.example.com/checkout/tx-987654321",
    "providerTransactionId": "ExPay-tx-12345"
  },
  "createdTime": "2023-01-01T12:00:00Z"
}

Example Callback Data

{
  "transactionId": "tx-987654321",
  "requestId": "req-123456789",
  "accountId": 12345,
  "transactionStatus": "COMPLETED",
  "declineCode": null,
  "declineSubReason": null,
  "orderCurrency": "USD",
  "processedCurrency": "USD",
  "orderAmount": 100.0,
  "processedAmount": 100.0,
  "conversionRate": 1.0,
  "apmRequestPayload": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    // Original request payload
  },
  "apmResponseData": {
    "paymentMethod": "ExPay",
    "paymentType": "E_WALLET",
    "redirectUrl": "https://pay.ExPay.example.com/checkout/tx-987654321",
    "providerTransactionId": "ExPay-tx-12345"
  },
  "callbackUrl": "https://merchant.example.com/callbacks/payments",
  "billingDetails": {
    // Original billing details
  },
  "order": {
    // Original order details
  },
  "createdAt": "2023-01-01T12:00:00Z"
}

Additional API Endpoints

Additional API Endpoints

Get Payment Information

Retrieve detailed information about a specific transaction.

GET https://live.facilero.com/api/v1/payments/apm/info/{id}

Parameters

Response

Returns a JSON object containing detailed payment information in the ApmPaymentTxInfoDto format or an error message if the transaction is not found.

Payment Flow

1. Initiate Payment: Send a request to the APM API endpoint with the required payment details.

2. Process Response:

   • For redirect-based flows: Redirect the customer to the URL provided in apmResponseData.redirectUrl.
   • For iframe-based flows: Load the URL from apmResponseData.iframeUrl in an iframe.

3. Receive Callback: Once the payment is completed, a callback will be sent to the provided callbackUrl with the final transaction status and details.

4. Verify Status: You can also verify the transaction status by querying the /info/{id} endpoint.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 200 OK - Request successful
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication failure
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server-side error

Error responses include a descriptive message to help diagnose the issue.

⚠️ Important Note on Amount Formatting

In requests, the amount field is provided as a string (e.g., "200.00").
In callbacks, the amount field is returned as a double (e.g., 200.0).

Because Facilero uses native numeric types internally, trailing zeros after the decimal point may not be preserved. This means:

• Request → "200.00"
• Callback → 200.0

When generating or validating the checksum for callbacks, always use the exactamount value as provided in the callback payload, not the original request value.

This ensures checksum validation remains consistent and avoids mismatches caused by formatting differences.

Notes

• All monetary values should be passed as strings to maintain precision.
• The API supports different payment methods and flow types through the polymorphic apmPayload field.
• Always ensure proper validation of user inputs before submitting payment requests.
• The callback mechanism ensures you receive updates about transaction status changes.
• The apmResponseData object is crucial for completing the payment flow, as it contains the necessary redirection URLs or iframe URLs depending on the payment method.