One-Time Payments

This guide outlines the process for initiating a one-time card payment through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes.

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: Request a Card Payment

To initiate a one-time card payment, you'll need to send a POST request to the Create Payin endpoint.

Key Request Parameters

The request requires several key objects:

Parameter	Description	Required
`payer`	Payer information for compliance	✅
`merchant`	Merchant/business details	✅
`paymentMethod`	Payment method configuration	✅
`amount`	Transaction amount	✅
`currency`	Transaction currency code	✅
`country`	Target country code	✅

Example Request

Below is an example using curl:

curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "[email protected]"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "[email protected]"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'

See all available parameters in the request.

Payment with Tokenized Card

If you have previously tokenized a customer's card, you can use the token instead of sending the full card details to process a one-time payment. This enhances security and simplifies the payment flow by eliminating the need to request card information again.

For detailed information on card tokenization, please refer to the Tokenization documentation.

Payment with 3D Secure

If the cardholder requires additional authentication, the flow will proceed through 3D Secure. In this case, Localpayment returns the issuer’s challenge URL in the API response, and it is the merchant’s responsibility to redirect the customer or display the challenge within the checkout flow. This allows the cardholder to complete the required verification. The exact 3D Secure experience may vary depending on the issuer and the customer’s country.

For detailed information on 3D Secure payments, please refer to the 3D Secure documentation.

Step 2: Handle the Response

Successful Response

A successful response includes detailed transaction information and tracking identifiers:

{
  "transactionType": "PayIn",
  "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "[email protected]",
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": []
}

Key Response Fields

Parameter	Description	Use Case
`internalId`	Localpayment's unique transaction identifier.	Transaction tracking and support.
`externalId`	Your reference number.	Internal reconciliation.
`status.code`	Current transaction status code.	Status monitoring.
`date.creationDate`	When transaction was created.	Audit trail.
`date.processedDate`	When transaction began processing.	Processing time calculation.

Error Response

When a request fails, you'll receive detailed error information:

{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}

Step 3: Track Transaction Status

After initiating a one-time payment, monitor its 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
`103`	`APPROVED`	The payin was confirmed but not credited yet.
`200`	`Completed`	The payin was completed.
`300`	`Rejected`	Invalid param + [param name] + [reason].

📝
For complete status code reference, see the Transaction Status documentation.

Testing Your Integration

Test Scenarios

Verify your integration handles these scenarios:

Successful Transaction: Standard payin flow
Validation Errors: Invalid bank account, missing fields
Processing Delays: Transactions that take time to process
Failed Transactions: Insufficient funds, blocked beneficiaries
Status Updates: Webhook handling and status polling

Next Steps

After a one-time payment is processed, you may need to perform additional actions, such as:

Refund the transaction

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

Handle chargebacks

In case of a dispute, you may need to handle chargebacks. Refer to the documentation for information on this process.

Review transaction details

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