- 获取报价:调用货币兑换报价 API,并指定操作类型(
payin、payout或CurrencyExchange)。您将收到一个exchangeRateToken,其中包含有保证的汇率和到期时间。 - 使用令牌:在您的收款、付款或批量兑换请求中包含
exchangeRateToken。API 会自动应用已锁定的汇率。
汇率到期锁定的汇率仅在令牌的
expirationDate 之前有保证。如果令牌在您提交交易之前过期,该操作将使用当时的市场汇率。为收款报价
当您希望在收取付款之前向用户显示汇率时,请使用此流程。步骤 1:请求报价
请求curl
curl --request GET \
--url 'https://api.stage.localpayment.com/api/fx/currency-exchange/payin?sourceCurrency=ARS"eCurrency=USD&accountNumber={{accountNumber}}"eAccountNumber={{accountNumber}}' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'accept: application/json'
{
"exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca",
"transactionType": "PayIn",
"accountNumber": "{{accountNumber}}",
"sourceCurrency": "ARS",
"creationDate": "2024-12-27T21:33:32.6513692+00:00",
"expirationDate": "2024-12-28T05:33:32.6513692+00:00",
"quotes": [
{
"paymentMethodCode": "1005",
"rate": 0.0008369108482392735,
"quoteCurrency": "USD"
},
{
"paymentMethodCode": "1023",
"rate": 0.0008369108482392735,
"quoteCurrency": "USD"
},
{
"paymentMethodCode": "1000",
"rate": 0.0008369108482392735,
"quoteCurrency": "USD"
}
]
}
步骤 2:使用令牌提交收款
请求curl
curl --request POST \
--url https://api.stage.localpayment.com/api/payin/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"paymentMethod": {
"type": "CreditCard",
"code": "1000",
"flow": "DIRECT"
},
"externalId": "4423f38d-cc35-4ca9-8119-b9102059172d",
"country": "ARG",
"currency": "ARS",
"amount": 100,
"accountNumber": "{{accountNumber}}",
"conceptCode": "0001",
"comment": "APPROVED",
"exchangeRateToken": "5c3q89a7-f1bc-4ba5-a3b5-411ba0d144ca,
"merchant": {
"type": "COMPANY",
"name": "Company",
"document": {
"id": "3000091105",
"type": "CUIT"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "John",
"lastname": "Doe",
"document": {
"id": "37993123",
"type": "DNI"
},
"email": "john.doe@example.com",
"phone": {
"countryCode": "1",
"areaCode": "11",
"number": "98189123"
},
"bank": {
"account": {
"type": "C"
}
}
},
"metaData": {
"1finalStatus": "APPROVED",
"2finalStatus": "INPROGRESS"
},
"card": {
"name": "APPRO",
"number": "4970100000000055",
"cvv": "123",
"expirationMonth": "11",
"expirationYear": "2029",
"installments": 1,
"save": false
}
}
'
{
"transactionType": "PayIn",
"externalId": "949e5683-4320-4129-bf0a-ea3b027b6cd1",
"internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
"paymentMethod": {
"type": "CreditCard",
"code": "1000",
"flow": "DIRECT"
},
"country": "ARG",
"currency": "ARS",
"amount": 1002,
"accountNumber": "{{accountNumber}}",
"confirmed": {
"currency": "ARS",
"amount": 1002,
"fxQuote": 1,
"exchangeRateToken": null
},
"payment": {
"installment": null,
"currency": "ARS",
"fxQuote": 1,
"financingFee": 0,
"amount": 1002
},
"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": {
"token": "N66a0BVHGJY/oCwOyl/CbxIJ5DmCINWeir9PY9gxVGI=",
"bin": "402670",
"brand": "VISA",
"country": "RS",
"name": "John Doe",
"last4": "3263",
"expirationYear": 2029,
"expirationMonth": 9
},
"errors": []
}
curl
curl --request POST \
--url https://api.stage.localpayment.com/api/payout/ \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data '[{
"externalId": "3b7e91a0-2c4d-4f83-a1b2-d05143e2238a",
"country": "ARG",
"currency": "ARS",
"amount": 10000,
"accountNumber": "{{accountNumber}}",
"exchangeRateToken": "8f2d14b3-c4ea-4912-b7a1-922cd1e255fb",
"paymentMethod": {
"type": "BankTransfer",
"code": "1005",
"flow": "DIRECT"
}
}]'
在结账前显示汇率
如果您正在构建结账流程,并希望在用户确认付款之前向其显示汇率,流程如下:- 用户选择金额和货币。
- 您的后端调用货币兑换报价 API,并在
exchangeRateToken参数中接收汇率。 - 您的前端显示:“您将支付 10,000 ARS ≈ 8.37 USD(汇率:0.000837)”
- 用户确认。
- 您的后端使用
exchangeRateToken提交收款,以应用锁定的汇率。
expirationDate 之前提交,就能保证用户看到的汇率即为应用于该交易的汇率。
设计提示:在界面中以倒计时形式显示
expirationDate(例如 “汇率有效期为 8 小时”)。这样可以设定正确的预期,并减少因会话之间汇率变动而产生的支持工单。
