Skip to main content

Contracts

GET https://api-sandbox.letpay.io/merchant/contracts/list

Overview​

This method offers merchants a way to get data about their accounts.

A Contract in our system is a fundamental component used to define a specific set of business rules for a merchant's payment activities. These rules govern details such as accepted payment methods, associated fees, and the payment/settlement cycles.

Contracts serve as a mechanism to segregate different payment activities or business units within a single merchant account. For instance, a merchant can use a separate contract to distinguish sales from a global online store versus sales from a regional store, each with its own specific rules and configurations.

The specific API endpoint (/merchant/contracts/list) discussed is used to retrieve the contracts data associated with a merchant's account. Since a contract defines the business rules for processing transactions, the contract ID is a mandatory field for all transactions.

Contracts have three primary types:

  • PAYIN: For receiving payments.

  • PAYOUT: For making disbursements.

  • ID_VALIDATION: For identity verification processes.

    warning

    This endpoint (/merchant/contracts/list) should not be used in the transactional flow (i.e., when processing a customer payment or payout).

    In a high-volume transactional flow, the system must use a consistent and stable configuration. Therefore, the contract ID should be fixed and pre-configured in the merchant's application or e-commerce platform settings. This ensures reliability, speed, and integrity for every transaction without requiring a runtime lookup of the entire contracts list.

Response Body​

The response for this request can be represented as a JSON schema:

json
{
    "type": "object",
    "properties": {
        "refresh_token": { "type": "string" },
        "contracts": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "createdAt": { "type": "string" },
                    "contractType": { "type": "string" },
                    "name": { "type": "string" },
                    "active": { "type": "boolean" },
                    "id": { "type": "string" },
                    "methods": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "country": { "type": "string" },
                                "fees": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "country": { "type": "string" },
                                            "amount": { "type": "number" },
                                            "method": { "type": "string" },
                                            "endDate": { "type": "string" },
                                            "percentage": { "type": "number" },
                                            "active": { "type": "boolean" },
                                            "type": { "type": "string" },
                                            "value": { "type": "string" },
                                            "startDate": { "type": "string" }
                                        }
                                    }
                                },
                                "name": { "type": "string" },
                                "active": { "type": "boolean" },
                                "currency": { "type": "string" }
                            }
                        }
                    }
                }
            }
        },
        "timestamp": { "type": "string" },
        "status": { "type": "number" },
        "error": { "type": "string" },
        "message": { "type": "string" },
        "path": { "type": "string" }
    }
}

Example Request​

Example Request​

200 - Authenticated
  curl --location 'https://api-sandbox.letpay.io/merchant/contracts/list' \
  --header 'X-Auth-Token: MY_ACCESS_TOKEN'

Example Response​

Header
  Content-Type: application/json
Body
  {
  "refresh_token": "MY_ACCESS_TOKEN",
  "contracts": [
              {
              "createdAt": "2017-08-10T19:05:59.026",
              "contractType": "PAYIN",
              "name": "Storvo",
              "active": true,
              "id": "da51f472-d823-4120-b75c-ad5e10b1c02e",
              "methods": [
                  {
                  "country": "Brasil",
                  "fees": [
                      {
                      "country": "BR",
                      "amount": 0,
                      "method": "BOLETO",
                      "endDate": "2050-11-30",
                      "percentage": 3.9,
                      "active": true,
                      "type": "TRANSACTION_FEE",
                      "value": "3.90%",
                      "startDate": "2022-07-05"
                      },
                      {
                      "country": "BR",
                      "amount": 0.29,
                      "method": "BOLETO",
                      "endDate": "2050-11-30",
                      "percentage": 0,
                      "active": true,
                      "type": "PLATFORM_FEE",
                      "value": "USD 0.29",
                      "startDate": "2022-07-05"
                      }
                  ],
                  "name": "BOLETO",
                  "active": true,
                  "currency": "BRL"
                  }
              ]
              }
          ]
          }