Make your first test payment

Learn how to make your first test payment using Localpayment's sandbox environment. You'll learn how to authenticate, retrieve available payment methods, process a card payment, handle webhooks, and verify 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

Postman Collection

Download our ready-to-use Postman collection for faster testing

API Reference

Explore our complete API documentation with examples

Prerequisites

Before you begin, ensure you have:

Sandbox Account

Complete the onboarding process and obtain your test API credentials

API Access

Your sandbox username and password for generating access tokens

Webhook Endpoint

Set up a webhook URL to receive payment notifications

IP Whitelisting

Whitelist your server IP addresses for API access

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": "[email protected]",
  "password": "KD##ow^&Z2zD6^2FL29m"
}
'

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": "TESTARGUSD01",
    "accountNumber": "123.456.78900001",
    "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
          }
        }
      }
    ]
  }
]

📝
Note: 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.

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": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "032.032.00000000",
  "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"
  }
}'

Key Request Fields

Field	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	`032.032.00000000`
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

Successful Response

{
  "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": []
}

Key Response Fields

Field	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: Verify Transaction Status

You can proactively check transaction status using the Get Transaction Statusendpoint. 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
100	INPROGRESS	The payin is pending the confirmation
103	APPROVED	The payin was confirmed but not credited yet
200	COMPLETED	The payin was credited
801	REJECTED	Params error
819	REJECTED	Invalid payment method

📝
Important: Always check the status.code field to determine the transaction outcome.

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

Field	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

Field	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, bank transfers, cash, and digital wallets.

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.