概述
Localpayment 沙盒是一个完整的测试平台,它模拟了我们的生产环境,但不会处理真实交易。它提供了一个安全的空间,让您在正式上线前测试各种支付方式、货币和国家/地区的集成情况。沙盒环境
所有测试活动请使用我们专用的沙箱 API endpoint
测试数据
获取涵盖所有场景的全面测试卡和账户
实时仿真
接收所有测试交易的即时 webhook 通知
API 参考
浏览我们完整的 API 文档及示例
开始之前
开始之前,请确保您已准备好:API凭证
用于身份验证的有效 API 凭据和访问令牌。
账户设置
为您的目标国家/地区正确设置账户并进行业务验证。
IP白名单
将服务器 IP 地址加入 API 访问白名单。
Webhook endpoint
设置 webhook URL 以接收付款通知。
步骤 1:生成访问令牌
要与 Localpayment 的 API 进行交互,您需要一个用于身份验证的访问令牌。所有 API 请求都需要此令牌。 要生成访问令牌,您需要向生成访问令牌endpoint 发送POST 请求,并在请求正文中以 JSON 对象的形式包含您的 Localpayment username 和 password。
示例请求
curl
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}}"
}
'
成功响应
{
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGccM5kYO7o4iOiJIU18jaiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTczNTMxOTkyOSwianRpIjoiZWUxMDE3MTUwY2JhNGM1NTg0MjYyZmRkZTdiOThiNGQiLCJ1c2VyX2lkIjoxMDAwLCJzdXBlcnVzZXIiOnRydWUsImlzX3N0YWZmIjp0cnVlLCJybaCIsImV4cCI62xlcyI6WyJBTEwiXSwiY291bnRyaWVzIjpbIkFMTCJdLCJjb21wYW55IjoiQUxMIiwiY2xpZW50X2NvZGUiOiJBNzaW9uTEwiLCJwZXJtaXcyI6W119.6siymomkQ72yMvHGU9sMCO4h-cxpNgQXor",
"access": "eyJ0eXAiOiJKV1QiLCJhJIUzI1NiJ9.eyJ0b2tlbl90eXBlIbGciOijoiYWNjZXNzIiwiZXhwIjoxNzM1MjMzODI5LCJqdGkiOiJiMDRmNzQ3YWEjOCIsIn4Mjg0YjM0YmMwN2Y4ZjVkOWM0NWFVzZXJfaWQiOjEwMDAsInN1cGVydXNlciI6dHJ1ZSwiaXNfc3RhZmYiOnRy3VudHJpZXMiOljpbIkFsiQUxMIl0sImNvbXBhbnkiOiJBTEwiLCJjbGllbnRfY29kZSI6IkFMTCIsInBlcm1pc3Npb25zIjpdWUsInJvbGVzIMTCJdLlqEnH7GrECJjbbXX0.sWOLKFxCcXQkUcPvTjYceXBp39hDF3-Snc"
}
重要的在所有后续 API 请求中使用响应中的
access 令牌。将其作为 Bearer <your_access_token> 放入 Authorization 标头中。出于安全原因,令牌会过期 - 请使用刷新令牌获取新的访问令牌,而无需重新验证。步骤 2:检索可用的付款方式
创建付款前,请检查您的账户和目标国家/地区有哪些付款方式可用。 要获取可用的付款方式,请向获取可用的付款方式endpoint 发送GET 请求,并将您的 accountNumber 作为查询参数包含在内。
示例请求
curl
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'
成功响应
[
{
"accountCode": "TESTARG",
"accountNumber": "{{accountNumber}}",
"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
}
}
},
],
"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
}
}
}
]
}
]
对于银行卡支付,请查找
paymentMethodType 为 CreditCard 或 DebitCard 的支付方式。请记下 code 值(例如,阿根廷 Visa 卡对应的 1000),因为您在付款请求中需要用到它。步骤 3:创建付款请求
现在您可以创建您的第一笔测试付款了。我们将以阿根廷的信用卡付款为例。 要创建信用卡付款,请向创建付款endpoint 发送POST 请求,并在 Authorization 标头中包含您的 access 令牌。
关键请求字段
该请求需要几个关键参数:| 参数 | 类型 | 必需的 | 说明 | 例子 |
|---|---|---|---|---|
paymentMethod.type | string | ✅ | 支付方式类型 | CreditCard |
| paymentMethod.code | string | ✅ | 可用支付方式的代码 | 1000 |
| externalId | string | ✅ | 系统中的唯一标识符(使用 UUID4) | 40bac59a-0381-4cc0-a6a5-33418d84c2e4 |
| country | string | ✅ | ISO 3166-1 alpha-3 国家代码 | ARG |
| currency | string | ✅ | 交易货币代码 | ARS |
| amount | number | ✅ | 交易金额 | 1000 |
| accountNumber | string | ✅ | 您的Localpayment账号 | {{accountNumber}} |
| merchant | object | ✅ | 商家/企业信息 | 请参见下方商户对象 |
| payer | object | ✅ | 付款人/客户信息 | 请参见下方的付款人对象。 |
| card | object | — | 银行卡支付详情 | 请参见下方卡片对象。 |
示例请求
以下是使用curl 的示例:
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": "mail@company.com",
"phone": {
"countryCode": "54",
"areaCode": "351",
"number": "1234567"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"type": "DNI",
"id": "37993123"
},
"email": "john.doe@example.com",
"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"
}
}'
成功响应
成功的响应应包含详细的交易信息和跟踪标识符:{
"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": "{{accountNumber}}",
"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": "{{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": "37895247",
"type": "DNI"
},
"email": "john.doe@example.com",
"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": []
}
关键响应字段
| 参数 | 说明 | 用例 |
|---|---|---|
| transactionType | 处理的交易类型 | 确认这是用于付款请求的“PayIn” |
| externalId | 您的原始参考编号 | 内部对账和订单匹配 |
| internalId | Localpayment 的唯一交易标识符 | 支持和交易查询参考 |
paymentMethod.type | 使用的付款方式 | 核实正确的付款方式处理 |
| paymentMethod.code | 支付方式代码 | 确认预期付款方式 |
status.code | 当前交易状态 | 确定付款流程的后续步骤 |
status.description | 状态描述 | 显示用户友好的状态消息 |
status.detail | 详细状态信息 | 提供有关交易状态的具体上下文 |
| amount | 原始交易金额 | 核实预期金额是否已处理 |
date.creationDate | 交易创建时 | 分析和绩效跟踪 |
| errors | 错误详情数组 | 处理并显示任何交易错误 |
第四步:处理 Webhook 通知
Webhook 可提供交易状态变更的实时通知。请在 Localpayment Business Portal 中配置您的 Webhook URL 以接收这些通知。Webhook 载荷示例
{
"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": "{{accountNumber}}",
"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": "{{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": "37895247",
"type": "DNI"
},
"email": "john.doe@example.com",
"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": []
}
实施提示:您的 webhook endpoint 在收到 webhook 后应立即返回
200 OK 状态,然后异步处理通知以避免超时。步骤五:跟踪交易状态
您可以使用获取交易状态endpoint 主动检查交易状态。发送GET 请求,将 {externalId} 替换为您的唯一交易标识符,即可获取交易状态。
示例请求
curl
curl --request GET \
--url https://api.stage.localpayment.com/api/transactions/{externalId}/status \
--header 'Authorization: Bearer <your_access_token>' \
--header 'accept: application/json'
成功响应
{
"internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
"externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
}
}
常用状态码
| 代码 | 状态 | 说明 |
|---|---|---|
103 | APPROVED | 付款已确认,但尚未到账。 |
200 | Completed | 付款已完成。 |
300 | Rejected | 无效参数 + [参数名称] + [原因]。 |
重要的请务必检查
status.code 字段以确定交易结果。有关所有可能的交易状态的完整列表,请参阅完整的状态参考。测试不同的支付方式
Localpayment 除了信用卡之外,还支持多种支付方式。每种方式都有其特定的请求参数和响应结构。以下是银行转账的示例,并重点突出了关键区别。- 银行转账付款
银行转账支付允许客户通过本地支付系统直接从其银行账户付款。
示例请求
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": "mail@company.com",
"phone": {
"countryCode": "54",
"areaCode": "351",
"number": "1234567"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"type": "DNI",
"id": "37993123"
},
"email": "john.doe@example.com",
"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": "{{accountNumber}}",
"conceptCode": "0001"
}
'
成功响应
{
"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": "{{accountNumber}}",
"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": "{{accountNumber}}"
},
"status": {
"code": "100",
"description": "INPROGRESS",
"detail": "The payin is pending the confirmation"
},
"merchant": {
"type": "COMPANY",
"name": "Company",
"document": {
"type": "CUIT",
"id": "3000091105",
},
"email": "mail@company.com",
"phone": {
"countryCode": "54",
"areaCode": "351",
"number": "1234567"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"type": "DNI",
"id": "37993123"
},
"email": "john.doe@example.com",
"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"
}
银行转账的主要请求差异
| 参数 | 与银行卡支付的区别 | 例子 |
|---|---|---|
paymentMethod.type | 设置为 BankTransfer 而不是 CreditCard | BankTransfer |
paymentMethod.code | 使用银行转账专用代码 | 1040(Debin) |
payer.bank | 必填 - 银行账户信息 | 完整银行对象 |
| card 对象 | 无需 - 移除银行卡信息 | 省略 |
payer.bank.account.type | 账户类型规范 | S(储蓄) |
银行转账的关键响应差异
| 参数 | 与银行卡支付的区别 | 说明 |
|---|---|---|
paymentMethod.type | BankTransfer 而不是 CreditCard | 确认付款方式 |
status.code | 最初通常为 100(INPROGRESS) | 银行转账需要客户授权 |
| redirectUrl | 存在 - 用于客户授权的 URL | 引导客户完成付款 |
| card 对象 | 不存在 - 不返回银行卡详情 | 已替换为银行信息 |
| expirationDate | 存在 - 授权窗口 | 客户完成时间有限 |
后续步骤
探索收款选项
了解所有可用的支付方式,包括银行卡和 APM。
探索付款选项
了解如何向银行账户和电子钱包汇款。
探索国家/地区覆盖范围
查看各个国家/地区可用的付款方式、货币和具体要求。
API 参考
查看包含 endpoint、参数和代码示例的完整 API 文档。

