CODI (MEXICO)

Localpayment enables merchants to process instant payments through Mexico's CODI system, operated by Banco de México. This guide outlines the process for initiating CODI payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Mexico's real-time digital payment infrastructure.

Before You Begin

Ensure you have:

API Credentials

Valid API credentials and access token for authentication.

Account Setup

Proper account setup for your target country and business verification.

Country Requirements

Understanding of country-specific requirements and local regulations.

Step 1. Create CODI Payment

To generate a CODI payment request, send a POST request to the Create Payin endpoint with CODI-specific parameters.

Key Request Parameters

The request requires several key parameters specific to CODI payments:

Object	Description	Required
`paymentMethod.type`	Must be `BankTransfer`	✅
`paymentMethod.code`	Must be `1700`	✅
`payer`	Payer information	✅
`merchant`	Merchant/business details	✅
`amount`	Transaction amount	✅
`currency`	Transaction currency code	✅
`country`	Must be `MEX`	✅

See all available parameters in the request.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --data '
{
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1700",
        "flow": "DIRECT"
    },
    "currency": "MXN",
    "merchant": {
        "type": "COMPANY",
        "document": {
            "id": "EXTF900101NI1",
            "type": "RFC"
        },
        "name": "Test Company"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "document": {
            "id": "ABCD8104019Z3",
            "type": "RFC"
        },
        "name": "John",
        "lastname": "Doe"
    },
    "externalId": "505244a3-4743-4301-bd8c-924cf0401fac",
    "country": "MEX",
    "amount": 100,
    "accountNumber": "484.484.00000011",
    "conceptCode": "0001",
    "comment": "Payin CODI MEX"
}
'

Step 2. Handle the Response

Successful Response

A successful CODI payment creation includes the payment details and transaction reference:

{
    "transactionType": "PayIn",
    "externalId": "505244a3-4743-4301-bd8c-924cf0401fac",
    "internalId": "570a33ad-14b8-4fb8-b3ee-d23e648c47cf",
    "paymentMethod": {
        "type": "BankTransfer",
        "code": "1700",
        "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 100,
    "accountNumber": "484.484.00000011",
    "confirmed": {
        "currency": "MXN",
        "amount": 100,
        "fxQuote": 1
    },
    "payment": {
        "currency": "MXN",
        "fxQuote": 1,
        "financingFee": 0,
        "amount": 100
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
        "description": "Fee",
        "currency": "MXN",
        "fxSource": 17.095697,
        "fxQuote": 1,
        "amount": 1.5,
        "account": "484.484.00000011"
    },
    "status": {
        "code": "100",
        "description": "INPROGRESS",
        "detail": "The payin is pending the confirmation"
    },
    "qr": {
        "image": "https://web-checkout.stage.localpayment.com/api/og?internalId=570a33cd-a4b8-4fb8-b3ee-d23e648c47cf",
        "code": "{\"TYP\":20,\"v\":{\"DEV\":\"00000161803561219721/2\"},\"ic\":{\"IDC\":\"30416eb753\",\"SER\":88214934,\"ENC\":\"IEgzdIvvDu/uregux7FMxD/xdmR9OxfROPugkV1V1xi55O9OlRC7ssZFVeTTXkhrcjGqtj76z8JxajriLik9+ozDadCQBPRm9G5dQtxpmHm47Hzg2kEBBgWAdIEpt7SSrU1RHYr+UUv++uv07mOrtoy0kVfv2MT2vYNvxHoWWNBEZd2lHR5w0iQpu1NQOfTXVNyX7Rb83EgvjVh+ydj3QlXWLiizpbPto0aDgUim8cVT47ySmMKGmBJC4MmKLJ8bf0RdqMCazuzzRV7ByMIKxfBeKNqeV5CMezpanYiO9KURo5u1b1Pvb0ZCzCVaAdgfSEkUb8+Mlz+JI7g59lLAg0cYC0pl9ZrtWN1H/gyBOCI=\"},\"CRY\":\"UyfKyF8JM3L4EUHevl2itJMJxMJwe2OdjFb3P1eKd1I=\"}",
        "expirationDate": "2024-02-02T19:53:46.2179168"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Test Company",
        "document": {
            "type": "RFC",
            "id": "EXTF900101NI1"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "ABCD8104019Z3"
        }
    },
    "intermediaries": [],
    "date": {
        "creationDate": "2024-02-01T19:53:45.977+00:00",
        "processedDate": "2024-02-01T19:53:46.6065502",
        "expirationDate": "2024-02-02T19:53:46.2179168"
    },
    "errors": []
}

Key Response Fields

Parameter	Description	Use Case
`qr.image`	Pre-generated QR code image URL	Display ready-to-use QR code to customers without additional generation.
`qr.code`	Encrypted QR code payload in CODI standard format	For custom QR code generation or advanced integration scenarios.
`qr.expirationDate`	ISO timestamp when QR becomes invalid	Display countdown timer and handle expiration logic.
`externalId`	Your original reference number.	Internal reconciliation and order matching.
`status.code`	Current transaction state	Determine next steps in payment flow.
`date.creationDate`	When transaction was created.	Analytics and performance tracking.

Error Response

When CODI payment creation fails, you'll receive detailed error information:

{
  "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}

Step 3. Display QR Code and Handle Payment

QR Display: Present the pre-generated QR code from qr.image to customer.
Bank App Scan: Customer scans QR with their Mexican bank mobile app.
Payment Authorization: Customer confirms payment in their banking environment.
Real-time Confirmation: Localpayment receives instant payment notification.
Status Update: Your system receives webhook with payment confirmation.

Best Practices for QR Display

Minimum display size: 250x250 pixels for mobile scanning.
Maintain 1:1 aspect ratio without distortion.
Ensure high contrast (dark on light background).
Add quiet zone (white border) around QR code.
Include alt text (e.g. "QR Code Payment").
Show Clear Payment Instructions.
Handle Time-to-Live (TTL) and Expiration.

Step 4. Track Transaction Status

Monitor CODI payment progress through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.

Code	Status	Description
`100`	`INPROGRESS`	The payin is pending the confirmation
`812`	`REJECTED`	External Id already used - duplication

📝
Note: For complete status code reference, see the Transaction Status Documentation.

Testing Your Integration

Test QR Scenarios

Verify your integration handles these scenarios:

Successful Payment: Complete QR scan and payment flow.
QR Expiration: Handle expired QR codes gracefully.
Multiple Payment Attempts: Same QR scanned multiple times.
Status Updates: Webhook handling and status polling.

Next Steps

After implementing CODI payments, consider these additional capabilities:

Refund the transaction

If necessary, you can refund the payment to the customer. Refer to the documentation for details.

Review transaction details

You can retrieve transaction information using the Localpayment API for detailed insights.