This API is used to prepare the charge of a saved card through the SoftPoint iframe (3DS / Visa DCAP).
It returns a transfer_intent (valid 30 minutes), the gateway access_token and the payment object. Load the iframe with gateway, call submitPayment with payment, and send the iframe transaction_id with the transfer_intent to Transfer in — complete.
Note: Requires the Idempotency-Key header: the same key and body within 24 hours return the same intent; the same key with a different body returns 409. Amounts are in cents.
URL
{{interface_url}}/{{version}}/customers/{{customer_id}}/transfers/in/prepare
Method
POST
Headers
Authorization: Bearer {access_token} (or Api-Key), Idempotency-Key: {unique value per operation}
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| payment_method_id | Integer | Yes | A saved card of the customer. |
| amount | Integer | Yes | Amount, in cents. |
| currency | String | No | Default USD. |
URL Parameters
| Parameter | Required/Optional | Type | Description |
|---|---|---|---|
| customer_id | Required | Integer | Our customer ID (id returned by Create customer). |
Example Request (cURL)
curl --location --request POST '{{interface_url}}/{{version}}/customers/{{customer_id}}/transfers/in/prepare' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Idempotency-Key: {{$guid}}' \
--data '{
"payment_method_id": 90311,
"amount": 5000,
"currency": "USD"
}'
Example Response (JSON) — 200
{
"transfer_intent": "eyJpdiI6...",
"expires_at": "2026-11-05T18:46:18Z",
"preview": {
"location_id": 279685,
"amount": 5000,
"service_fee_percent": 3,
"service_fee_amount": 150,
"net_amount": 4850,
"currency": "USD"
},
"gateway": {
"location_id": 279685,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"environment": "sandbox"
},
"payment": {
"process_type": "sale",
"amount": "50.00",
"currency_iso": "USD",
"card_token": "GRYfiyggFSBV0670",
"send_dcap": 1,
"orderid": "CT-48213-20261105181618"
}
}
Error Responses
Format: { "error": { "code", "name", "message", "details" } }
| Status | Error | When |
|---|---|---|
| 400 | idempotency_key_required | Missing Idempotency-Key header. |
| 409 | idempotency_key_conflict | Key reused with a different body. |
| 404 | payment_method_not_found | Not a saved card of this customer. |
| 422 | processor_configuration_not_found | The card's location has no card processor. |
| 502 | gateway_unavailable | The gateway did not answer. Retry with the same key. |