Localpayment API responses provide clear indicators of request outcomes through HTTP status codes and structured status objects. While response structures may vary by endpoint, they consistently include key information for proper handling.
Standard HTTP status codes indicating request success or failure
Detailed status information for transaction outcomes
Structured error information for debugging and resolution
HTTP Status Codes
The API uses standard HTTP status codes to indicate request outcomes at the protocol level. These codes provide the first indication of whether your request was successful.
Success Codes (2xx)
| Status Code | Description | Typical Use Cases |
|---|---|---|
| 200 OK | Request successful | GET requests, successful operations, data retrieval |
| 201 Created | Resource created successfully | New payments, virtual accounts, payouts |
Client Errors (4xx)
| Status Code | Description | Common Causes |
|---|---|---|
| 400 Bad Request | Malformed request or invalid parameters | Missing required fields, invalid data formats, validation errors |
| 401 Unauthorized | Authentication required or invalid | Missing/invalid access token, expired tokens, invalid credentials |
| 403 Forbidden | Insufficient permissions | IP not whitelisted, account restrictions, unauthorized access |
| 404 Not Found | Resource not found | Invalid transaction IDs, incorrect endpoints, deleted resources |
| 429 Too Many Requests | Rate limit exceeded | Too many API calls in short period, exceeded quota |
Server Errors (5xx)
| Status Code | Description | Recommended Action |
|---|---|---|
| 500 Internal Server Error | Unexpected server error | Retry with exponential backoff, contact support if persistent |
| 502 Bad Gateway | Upstream service unavailable | Retry after short delay, check system status |
| 503 Service Unavailable | Temporary service interruption | Check status page, retry later, implement circuit breaker |
Status Object
The status object provides detailed, Localpayment-specific information about transaction outcomes and is included in most API responses involving financial operations.
Status Object Structure
{
"status": {
"code": "103",
"description": "APPROVED",
"detail": "The payin was confirmed but not credited yet"
}
}Status Object Fields
| Field | Type | Description | Example |
|---|---|---|---|
code | string | Localpayment-specific status code | 103, 200, 701 |
description | string | Human-readable status summary | Approved, "Completed", "Rejected" |
detail | string | Additional context or explanation | The payin is pending the confirmation |
Common Response Patterns
Successful Payment Response
{
"transactionType": "PayIn",
"externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
"internalId": "dd616d71-f5cd-4bb5-9c2c-f421241ab301",
"paymentMethod": {
"type": "BankTransfer",
"code": "1099",
"flow": "DIRECT"
},
"country": "ARG",
"currency": "ARS",
"amount": 2300,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "ARS",
"amount": 2300,
"fxQuote": 1
},
"payment": {
"currency": "ARS",
"fxQuote": 1,
"financingFee": 0,
"amount": 2300
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "USD",
"fxSource": 1,
"fxQuote": 1020.72259627,
"amount": 0.6,
"account": "{{accountNumber}}"
},
"status": {
"code": "103",
"description": "APPROVED",
"detail": "The payin was confirmed but not credited yet"
},
"merchant": {
"type": "COMPANY",
"name": "LTDA",
"document": {
"type": "CUIL",
"id": "30-31.145.201-7"
},
"email": "[email protected]",
"phone": {
"countryCode": "countryCode",
"areaCode": "11",
"number": "98789632"
},
"address": {
"street": "Street",
"number": "938",
"city": "City",
"state": "state",
"country": "Argentina",
"zipCode": "1688",
"comment": "port 801"
},
"birthdate": "2000-01-01",
"nationality": "nationality"
},
"payer": {
"bank": {
"name": "Bank Name",
"code": "191",
"account": {
"type": "S",
"number": "1910119655111901676653"
}
},
"type": "INDIVIDUAL",
"name": "Prueba",
"lastname": "Test",
"document": {
"type": "CUIT",
"id": "20276201078"
},
"email": "[email protected]",
"phone": {
"countryCode": "1",
"areaCode": "11",
"number": "98789632"
},
"address": {
"street": "Street",
"number": "1234",
"city": "City",
"state": "state",
"country": "Country",
"zipCode": "1686",
"comment": "May the force be with you, always!"
},
"birthdate": "01/01/1990",
"nationality": "American"
},
"intermediaries": [],
"wireInstructions": {
"beneficiary": {
"bank": {
"name": "BANCO MACRO S.A.",
"code": "0118",
"branch": {},
"account": {
"type": "S",
"number": "2850328631194198460271"
}
},
"type": "INDIVIDUAL",
"name": "LOCALPAYMENT S.R.L.",
"document": {
"type": "CUIT",
"id": "30716132028"
}
},
"referenceCode": "1022000084"
},
"date": {
"creationDate": "2024-12-30T18:50:10.124+00:00",
"processedDate": "2024-12-30T18:50:10.6159529",
"expirationDate": "2025-01-06T18:50:10.5803114"
},
"errors": []
}Error Response Pattern
{
"externalId": "8c0b537a-e907-4d87-93db-5dab9807e093",
"internalId": "dddfde6c-b61c-4b0e-8916-d88886133c4d",
"status": {
"code": "701",
"description": "REJECTED"
},
"errors": [
{
"code": "701",
"detail": "Invalid bank account number. Account number verification failed."
}
]
}Transaction Status and Error Guide
Select a specific transaction type below for a detailed list of its statuses and error codes.
Status and error codes for receiving funds via virtual accounts, cards, and APMs.
Status and error codes for sending funds to beneficiaries.
Status and error codes for returning funds to a customer.
Status and error codes for disputed transactions and forced reversals.
Status and error codes for returned payments and failed settlements.
Status and error codes for payment recalls and reversals.
Status and error codes for credit transactions and adjustments.
Status and error codes for debit transactions and fund deductions.
Status and error codes for recurring billing and subscription lifecycles.
Status and error codes for foreign exchange transactions.
Status and error codes for incoming wire transfers.
Status and error codes for outgoing wire transfers.
Status and error codes for fee deductions and expense transactions.
Status and error codes for periodic fee charges.
Related Resources
Pro Tip
Implement comprehensive logging that captures both status codes and error codes with timestamps. This creates clear audit trails for compliance requirements and makes debugging issues significantly faster. Include the full error response in logs, not just the error code.