Quick Start

1. Essential Prerequisites

Before you begin integrating with the LATAM Pass APIs, you must complete the following commercial and technical requirements.

1.1 Obtain Business Identifiers

The key identifiers you need are:

• PartnerID: a unique identifier for your company (e.g: 09989092000121 or OHUTA). The same ID is used for both Sandbox and Production environments.
• ProductID: a specific identifier used to track accumulation transactions.

How can I get the partnerID and productID? Your commercial focal point should send them to you. You can contact them to obtain these identifiers if it has not been sent yet.

What should I do if I didn't receive it? Please contact our support team in case you were not able to contact your focal point.

1.2 Authentication Setup (Auth)

Our APIs utilize the OAuth 2.0 standard. To interact with any endpoint, you must include a valid access_token in your request headers.

Follow these steps to set up your access:

Step 1- Register Your App: Navigate to Dev Tools > Register App section to create your application profile.

Step 2- Select the API: Select which API you want to use, always checking the OAuth option.

Once you have registered the application by selecting the desired APIs from Dev Tools, you will be able to access the list of your registered apps.

By clicking on the "Details" and "Authorization" buttons, you will be able to access your authorization code.

With that authorization code, you can use our access-token API to generate your token and use it in the other APIs.

Without the access token, you will not be able to use them.

Step 3- Retrieve Your Credentials: Once the app is approved, go to Dev Tools > My Apps, select your newly created app, and click "See details" to access:

2. Obtain Authentication

Build Your POST Request to get the access-token parameter.

2.1 Prepare Your Authentication Request

Use this curl to get the POST method and fill the missing parameters. Remember: this is an example of how it should look. Please replace the client_id and authorization fields with the values you obtained from the previous section

curl https://api.latampass.com/sandbox/oauth/access-token \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'client_id: <<your_client_id>>' \
  --header 'authorization: Basic <<your_authorization_code>>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'

2.2 Configure Request Headers

Once you get client_id and authorization code as described in the Essential Prerequisites section, set the following headers in your request:

Important Required Fields

Once you send the request with the headers and body suggested correctly, you will receive a status 201 and this response:

{
  "access_token": "<YOUR_ACCESS_TOKEN>",
  "token_type": "access_token",
  "expires_in": 1000000
}

3. Build your POST

Build Your POST Request with your partner parameters and credentials

3.1 Use our APIs

If you want to use the Accrual PNA v2 API, use this curl command and replace the incomplete attributes with your partner credentials, authentication codes, and other body parameters, which you should already have if you read the previous sections.

In this example case, we will use the accrual request to submit an accrual application.

curl https://api.latampass.com/sandbox/v2/customer/loyalty/partner/accrual \
  --request POST \
  --header 'x-Latam-Test: LatamPass' \
  --header 'client_id: <insert your client id here>' \
  --header 'access_token: <insert your access token here>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonAirAccrual": {
      "quantity": 1000,
      "description": "PURCHASE TV 4K 60\" BLACK",
      "partner": {
        "partnerId": "<insert your partner ID HERE obtained with Latam commercial team>",
        "productId": "<use your own product code HERE, alphanumeric mandatory>",
        "partnerAccrualId": "<use your unique identifier HERE, alphanumeric, mandatory>",
        "partnerTransactionId": "<use your unique identifier HERE, alphanumeric, mandatory>",
        "partnerOriginalDateTime": "yyyy-mm-ddThh:mm:ss-<time-zone>:00"
      },
      "member": {
        "ffn": "7000000013",
        "firstName": "Carlos Jose",
        "lastName": "Silva Santos",
        "birthDate": "1900-12-30",
        "gender": "FEMALE",
        "email": "carlos.santos@email.com",
        "residenceCountryCode": "AW",
        "phone": {
          "countryCode": 55,
          "areaCode": 11,
          "phoneNumber": 999998888
        },
        "document": {
          "documentId": "12345678900",
          "documentType": "CPF",
          "issueCountryCode": "BR"
        }
      }
    }
  }'

More information about the fields in this sample API request:

4. Handle the Accrual Response

Handle accepted status and possible errors from the example step 3

4.1 Status and Meanings

If you receive a 200 OK response, it means your request was successfully accepted for processing.

• Parse the AccrualResponseV2 body and store the correlationId. This is your primary key for tracking the transaction.
• If you receive a 4xx or 5xx error, log the response body for debugging.
• Do not retry 4xx errors without correcting the request.

4.2 Verify the Final Transaction Status

If your transaction was generated correctly (receive a 200 OK response), you can verify the transaction status with 2 methods: automatic webhook and manually.

Option 1: Receive Notifications (Webhook) – Recommended

Action: Configure an endpoint (URL) in your system that can receive POST notifications. When the transaction status changes, the Accrual API will send you a notification with the correlationId and the final status.

Process: Your system must be listening at that URL to receive the notification and update the transaction status in your records.

More info about webhook here

Option 2: Query the Endpoint (Polling)

• Action: Make periodic GET calls to the query endpoint using the correlationId received in step 4.

URL:

curl 'https://api.latampass.com/sandbox/v2/customer/loyalty/partner/accrual?partnerIdentifier=<your partner ID>&correlationId=<your generated correlation ID>' \
  --header 'x-Latam-Test: LatamPass' \
  --header 'client_id: <Your client id>' \
  --header 'Access_token: <your access token>'

End Condition: Stop polling when the status field in the response is PROCESSED or CANCELLED

4.3 Issues and Solutions

5. Integration Checklist

Check here if you completed all the steps necessary

5.1 Accrual API Integration Checklist

✅ Authentication: Am I including the authentication token (access_token) in the Authorization header of all my requests?

✅ Member Identification: Am I sending the FFN or a complete document object (documentId, documentType, issueCountryCode) to identify the member in each accrual request?

✅ Partner Identifiers: Am I generating and sending the three required unique identifiers in the partner object?

productId

partnerAccrualId

partnerTransactionId

✅ Idempotency: To avoid duplicates, am I using the partnerAccrualId consistently for the same transaction? If I resend a transaction due to a network failure, do I use the same partnerAccrualId?

✅ Response Handling:

• Does my logic correctly interpret a 200 OK / 204 No Content response as a successful acceptance of the request?
• Can my logic handle a 4xx response (e.g., 400 Bad Request) and log the correlationId and error message for debugging?

✅ correlationId Logging: Am I storing the correlationId returned in the success response?

6. Production Access Guide

Make sure you completed all items to check your production readiness

Before requesting production access, ensure:

• ✅ All internal tests completed successfully in Sandbox
• ✅ No technical issues between partner and LATAM Pass
• ✅ Integration approved by LATAM Pass team
• ✅ Security requirements validated

6.1 Production Readiness Steps

1. Complete Integration in Sandbox

Successfully complete all test scenarios in the Sandbox environment

2. Request Production Approval

In order for the integration to be approved, LATAM Pass must:

• Ensure services and rules are properly configured in your test APP
• Request evidence of transactions carried out in the test environment

3. Receive Production Credentials

Once approved, you will receive:

• Production client_id
• Production client_secret
• Production access instructions

6.2 Environments: Sandbox vs. Production

6.3 How to Request Access

1. Access Requirements

• Access via Dev Tools > Register App functionality
• Wait for team approval (not automatic like Sandbox)
• Receive confirmation e-mail from the team

2. Assisted Production Process

• Open a ticket at the Support Center requesting assisted production
• Support team will define how evidence must be generated
• Evidence will be shared with the team

3. Security Requirements

• Production APP will remain in "Pending" status until approved
• Team will contact you for alignment and corrections
• Production APP will be automatically disabled for security reasons

6.4 Production Endpoints

6.5 Common Production Issues and Solutions