Make your first test payment

Get started by making your first test payment with the Localpayment API in the sandbox environment. You’ll authenticate your requests, explore available payment methods, run a card payment, manage webhooks, and check the final transaction status.

Overview

The Localpayment Sandbox is a complete testing platform that mirrors our production environment without processing real transactions. It provides a secure space to test your integration across various payment methods, currencies, and countries before going live.

Sandbox Environment

Use our dedicated sandbox API endpoint for all testing activities

Test Data

Access comprehensive test cards and accounts for all scenarios

Real-time Simulation

Receive instant webhook notifications for all test transactions

API Reference

Explore our complete API documentation with examples

Before You Begin

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.

IP Whitelisting

Whitelist your server IP addresses for API access.

Webhook Endpoint

Set up a webhook URL to receive payment notifications.

Step 1: Generate Access Token

To interact with Localpayment's API, you need an access token for authentication. This token is required for all API requests.

To generate an access token, you'll need to make a POST request to the Generate an Access Token endpoint with your Localpayment username and password included in the request body as a JSON object.

Example Request

curl --request POST \
     --url https://api.stage.localpayment.com/api/token/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "username": "{{UserName}}",
  "password": "{{password}}"
}
'

Successful Response

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
  "access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}

⚠️
Important
Use the access token from the response in all subsequent API requests. Include it in the Authorization header as Bearer <your_access_token>. Tokens expire for security reasons - use the refresh token to obtain new access tokens without re-authenticating.

Step 2: Retrieve Available Payment Methods

Before creating a payment, check which payment methods are available for your account and target country.

To get the available payment methods, send a GET request to the Get Available Payment Methods endpoint, including your accountNumber as a query parameter.

Example Request

curl --request GET \
     --url 'https://api.stage.localpayment.com/api/resources/payment-methods?accountNumber=1234567890' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Successful Response

[
  {
    "accountCode": "TESTARG",
    "accountNumber": "123.456.12345678",
    "countryISOCode3": "ARG",
    "moR": null,
    "mid": "0",
    "payinPaymentMethods": [
      {
        "id": 30,
        "code": "1005",
        "name": "Visa",
        "description": "Visa",
        "url": "https://cdn.localpayment.com/logos/visa-debit.png",
        "paymentMethodType": "DebitCard",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 24,
        "code": "1023",
        "name": "ITAU",
        "description": "ITAU",
        "url": "https://cdn.localpayment.com/logos/itau.png",
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 19,
        "code": "1000",
        "name": "Visa",
        "description": "Visa",
        "url": "https://cdn.localpayment.com/logos/visa.png",
        "paymentMethodType": "CreditCard",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 23,
        "code": "1004",
        "name": "Santander",
        "description": "Santander",
        "url": "https://cdn.localpayment.com/logos/santander.png",
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      },
      {
        "id": 21,
        "code": "1002",
        "name": "Pago facil",
        "description": "Pago Facil",
        "url": "https://cdn.localpayment.com/logos/pagoFacil.png",
        "paymentMethodType": "Cash",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      }
    ],
    "payoutPaymentMethods": [
      {
        "id": 87,
        "code": "2000",
        "name": "BBVA",
        "description": "Banco Frances",
        "url": null,
        "paymentMethodType": "BankTransfer",
        "transactionType": 0,
        "country": {
          "id": 0,
          "code": "032",
          "name": "Argentina",
          "isoCode3": "ARG",
          "localCurrency": {
            "code": "032",
            "name": "Argentine peso",
            "isoCode3": "ARS",
            "decimals": 2,
            "isHard": false
          }
        }
      }
    ]
  }
]

📝
For card payments, look for payment methods where paymentMethodType is CreditCard or DebitCard. Note the code value (e.g., 1000 for Visa in Argentina) as you'll need it for the payment request.

Step 3: Create a Payment Request

Now you're ready to create your first test payment. We'll use a credit card payment for Argentina as an example.

To create a credit card payment, send a POST request to the Create Payin endpoint, including your access token in the Authorization header.

Key Request Fields

The request requires several key parameters:

Parameter	Type	Required	Description	Example
paymentMethod.type	string	✅	Payment method type	`CreditCard`
paymentMethod.code	string	✅	Payment method code from available methods	`1000`
externalId	string	✅	Unique identifier from your system (use UUID4)	`40bac59a-0381-4cc0-a6a5-33418d84c2e4`
country	string	✅	ISO 3166-1 alpha-3 country code	`ARG`
currency	string	✅	Transaction currency code	`ARS`
amount	number	✅	Transaction amount	`1000`
accountNumber	string	✅	Your Localpayment account number	`123.456.12345678`
merchant	object	✅	Merchant/business information	See merchant object below
payer	object	✅	Payer/customer information	See payer object below
card	object	—	Card payment details	See card object below

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": "1000",
    "flow": "DIRECT"
  },
  "externalId": "{{$guid}}",
  "country": "{{country}}",
  "currency": "{{currency}}",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "conceptCode": "0001",
  "merchant": {
    "type": "COMPANY",
    "name": "Company",
    "document": {
      "type": "CUIT",
      "id": "3000091105",
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "351",
      "number": "1234567"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "DNI",
      "id": "37993123"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98189123"
    },
    "bank": {
      "name": "BANCO BBVA ARGENTINA S.A.",
      "code": "017",
      "account": {
        "type": "S",
        "number": "19101196551119123456789"
      }
    }
  },
  "commercialData": {
    "items": [
      "id": "12345",
      "quantity": "1",
      "description": "Test product",
      "title": "Test",
      "unitPrice": "1000"
    ]
  },
  "card": {
    "name": "John Doe",
    "number": "4000000000000002",
    "cvv": "123",
    "expirationMonth": "12",
    "expirationYear": "2029"
  }
}'

Successful Response

A successful response includes detailed transaction information and tracking identifiers:

{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "123.456.12345678",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "032.032.00000001"
  },
  "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": "37895247",
      "type": "DNI"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "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": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}

Key Response Fields

Parameter	Description	Use Case
transactionType	Type of transaction processed	Confirm this is "PayIn" for payment requests
externalId	Your original reference number	Internal reconciliation and order matching
internalId	Localpayment's unique transaction identifier	Reference for support and transaction lookup
paymentMethod.type	Payment method used	Verify correct payment method processing
paymentMethod.code	Payment method code	Confirm expected payment method
status.code	Current transaction state	Determine next steps in payment flow
status.description	Status description	Display user-friendly status messages
status.detail	Detailed status information	Provide specific context about transaction state
amount	Original transaction amount	Verify expected amount was processed
date.creationDate	When transaction was created	Analytics and performance tracking
errors	Array of error details	Handle and display any transaction errors

Step 4: Handle Webhook Notifications

Webhooks provide real-time notifications about transaction status changes. Configure your webhook URL in the Localpayment Dashboard to receive these notifications.

Webhook Payload Example

{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "032.032.00000001"
  },
  "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": "37895247",
      "type": "DNI"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "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": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}

✅
Implementation Tip:
Your webhook endpoint should return a 200 OK status immediately upon receiving the webhook, then process the notification asynchronously to avoid timeouts.

Step 5: Track Transaction Status

You can proactively check transaction status using the Get Transaction Status endpoint. Send a GET request, replacing {externalId} with your unique transaction identifier to obtain the transaction status.

Example Request

curl --request GET \
     --url https://api.stage.localpayment.com/api/transactions/{externalId}/status \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Successful Response

{
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  }
}

Common Status Codes

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].

⚠️
Important
Always check the status.code field to determine the transaction outcome. For the full list of possible transaction statuses, see the complete status reference.

Testing Different Payment Methods

Localpayment supports various payment methods beyond credit cards. Each method has specific request parameters and response structures. Below are examples for bank transfers and cash payments with key differences highlighted.

Bank transfer payments allow customers to pay directly from their bank accounts through local payment schemes.

Example Request

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": "BankTransfer",
    "code": "1040",
    "flow": "DIRECT"
  },
  "currency": "ARS",
  "merchant": {
    "type": "COMPANY",
    "name": "Company",
    "document": {
      "type": "CUIT",
      "id": "3000091105",
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "351",
      "number": "1234567"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "DNI",
      "id": "37993123"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98189123"
    },
    "bank": {
      "name": "BANCO BBVA ARGENTINA S.A.",
      "code": "017",
      "account": {
        "type": "S",
        "number": "19101196551119123456789"
      }
    }
  },
  "externalId": "0fcd5d00-a734-46d9-95d7-246126989132",
  "country": "ARG",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "conceptCode": "0001"
}
'

Key Request Differences for Bank Transfers

Parameter	Difference from Card Payments	Example
paymentMethod.type	Set to `BankTransfer` instead of `CreditCard`	`BankTransfer`
paymentMethod.code	Use bank transfer specific codes	`1040` (Debin)
payer.bank	Required - Bank account details	Full bank object
card object	Not required - Remove card details	Omitted
payer.bank.account.type	Account type specification	`S` (Savings)

Successful Response

{
  "transactionType": "PayIn",
  "externalId": "0fcd5d00-a734-46d9-95d7-246126989132",
  "internalId": "d05dab30-485f-473d-844c-041ed5355fc4",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1040",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "confirmed": {
    "currency": "ARS",
    "fxQuote": 1,
    "amount": 1
  },
  "payment": {
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "032.032.00000000"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company",
    "document": {
      "type": "CUIT",
      "id": "3000091105",
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "54",
      "areaCode": "351",
      "number": "1234567"
    }
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "DNI",
      "id": "37993123"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98189123"
    },
    "bank": {
      "name": "BANCO BBVA ARGENTINA S.A.",
      "code": "017",
      "account": {
        "type": "S",
        "number": "19101196551119123456789"
      }
    }
  },
  "intermediaries": [],
  "date": {
    "creationDate": "2025-02-16T20:04:04.993",
    "processedDate": "2025-02-16T20:04:10.969",
    "expirationDate": "2025-02-23T20:04:05.553"
  },
  "errors": [],
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/L3ZlcmlmaWNhdGlvbi8wMTM5P2ludGVybmFsSWQ9MGRlNmI5MmQtYjY0Yi00YThhLThjNGEtYjczNDk3ZWRhZDQx"
}

Key Response Differences for Bank Transfers

Parameter	Difference from Card Payments	Description
paymentMethod.type	`BankTransfer` instead of `CreditCard`	Confirms payment method
status.code	Often `100` (`INPROGRESS`) initially	Bank transfers require customer authorization
redirectUrl	Present - URL for customer authorization	Direct customer to complete payment
card object	Not present - No card details returned	Replaced with bank information
expirationDate	Present - Authorization window	Limited time for customer to complete

Next Steps

Explore Payins Options

Discover all available payment methods including cards, cash, and APMs.

Explore Payouts Options

Learn about sending payments to bank accounts and digital wallets.

Discover Country Coverage

Check available payment methods, currencies, and specific requirements for each country.

API Reference

Access complete API documentation with endpoints, parameters, and code examples.