Responses

This section details the response formats, HTTP status codes, and status objects used by the Localpayment API. Understanding these response patterns is essential for building robust integrations and handling various API outcomes effectively.

Overview

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.

HTTP Status Codes

Standard HTTP status codes indicating request success or failure

Status Objects

Detailed status information for transaction outcomes

Clear Error Handling

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": "032.032.00000015",
  "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": "032.840.00000005"
  },
  "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."
    }
  ]
}

Related References

For detailed information about specific status and error codes, refer to these dedicated resources:

Transaction Status

Complete reference of all transaction status codes and their meanings

Error Codes

Comprehensive list of error codes and troubleshooting guidance