Developers

Search for documents

Dev

Payments

Operations related to payments and refunds

All endpoints require a JWT Bearer token in the Authorization header and an API key in the X-API-KEY header.

Base URL: https://payments.valpay.com.

POST `/v1/payments/create`

Create a new payment

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	No	Optional. A unique key for this payment. Send the same key when retrying (e.g. after a timeout) so the payment is de-duplicated by Adyen and never charged twice. Strongly recommended for server-to-server clients.

Request body (required)

Field	Type	Required	Description
`amount`	`object`	Yes
`store`	`string`	Yes	Store ID
`apiVersion`	`integer`	No	Adyen Web-SDK artifact. Optional — the Adyen Checkout API version is pinned server-side, so you do not need to send it.
`reference`	`string`	Yes	Payment reference
`shopperInteraction`	`string (enum)`	No	Type of shopper interaction. Optional — when omitted the default is resolved from the charge type: a fresh charge defaults to "Ecommerce", while a token charge (storedPaymentMethodId) defaults to "ContAuth" (merchant-initiated). Supply an explicit value to override. One of: `Ecommerce`, `ContAuth`, `Moto`, `POS`
`additionalData`	`object`	No	Additional data for the payment
`paymentMethod`	`object`	Yes
`returnUrl`	`string`	No	Return URL after payment. Web/redirect (3DS) flows only — optional for raw server-to-server (e.g. MOTO) partner payments.
`merchantAccount`	`string`	No	Optional. The Adyen merchant account is derived server-side from the store, so you do not need to send it; any value provided is ignored.
`shopperReference`	`string`	No	Your unique identifier for the shopper (max 255 chars). Links payments and stored payment methods together. Required when charging a stored payment method (storedPaymentMethodId); otherwise optional.
`storePaymentMethod`	`boolean`	No	Set to true to tokenize the payment method for future charges. Requires recurringProcessingModel. Optional.
`recurringProcessingModel`	`string`	No	Processing model for stored/recurring payments (e.g. CardOnFile, Subscription, UnscheduledCardOnFile). Required when storePaymentMethod is true OR when charging a stored payment method (storedPaymentMethodId); otherwise optional.
`billingAddress`	`object`	No	Cardholder billing address. Improves AVS / risk checks. Optional.
`shopperEmail`	`string`	No	Shopper email. Optional; recommended by Adyen for risk scoring.
`shopperIP`	`string`	No	Shopper IP address (IPv4 or IPv6). Optional; recommended by Adyen for risk scoring.
`shopperName`	`object`	No	Shopper name. Optional; used for risk checks.
`telephoneNumber`	`string`	No	Shopper telephone number. Optional.
`merchantOrderReference`	`string`	No	Your reference for the order (max 80 chars), useful when an order spans multiple payments. Optional.
`shopperStatement`	`string`	No	Text shown on the cardholder's statement. Max 22 chars; allowed characters: a-z A-Z 0-9 space and . , ' _ - ? + * /. Optional.

Responses

Status	Description
`200`	Payment created successfully
`400`	Bad request

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

POST `/v1/payments/refund`

Refund a payment

Process a refund for a payment transaction. Note: The merchantAccount will be automatically added by middleware and should not be included in the request.

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID of the payment to refund
`splits`	`array<object>`	No	An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms
`amount`	`object`	Yes

Responses

Status	Description
`200`	Refund processed successfully
`400`	Bad request
`429`	Too many requests

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

POST `/v1/payments/void`

Void a payment

Process a void for a payment transaction. Note: The merchantAccount will be automatically added by middleware and should not be included in the request.

Request body (required)

Field	Type	Required	Description
`transactionId`	`string`	Yes	Transaction ID of the payment to void
`splits`	`array<object>`	No	An array of objects specifying how the amount should be split between accounts when using Adyen for Platforms
`amount`	`object`	Yes

Responses

Status	Description
`200`	Void processed successfully
`400`	Bad request
`429`	Too many requests

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

GET `/v1/payments/refundable-amount/{id}`

Get refundable amount for a payment

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Transaction ID to retrieve refundable amount for

Responses

Status	Description
`200`	Refundable amount retrieved successfully
`404`	Transaction not found

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

GET `/v1/payments/void-status/{id}`

Get void status for a payment

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Transaction ID to retrieve void status for

Responses

Status	Description
`200`	Void status retrieved successfully
`404`	Transaction not found

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

POST `/v1/payments/get-payment-methods`

Get available payment methods for a merchant account

Request body (required)

Field	Type	Required	Description
`action`	`string (enum)`	Yes	Action to perform One of: `getPaymentMethods`
`config`	`object`	Yes

Responses

Status	Description
`200`	Payment methods retrieved successfully
`400`	Bad request - validation failed
`401`	Unauthorized - invalid or missing authentication
`500`	Internal server error

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	Yes	Whether the operation was successful
`data`	`object`	Yes
`message`	`string`	Yes	Success message

Examples

POST `/v1/payments/refund`

curl -X POST https://payments.valpay.com/v1/payments/refund \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 1000, "currency": "USD" }
  }'

curl -X POST https://payments.valpay.com/v1/payments/refund \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 1000, "currency": "USD" }
  }'

curl -X POST https://payments.valpay.com/v1/payments/refund \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 1000, "currency": "USD" }
  }'

Response 200:

{
  "success": true,
  "data": { "pspReference": "PSPREF_EXAMPLE_456", "status": "received" },
  "message": "Refund processed successfully"
}

{
  "success": true,
  "data": { "pspReference": "PSPREF_EXAMPLE_456", "status": "received" },
  "message": "Refund processed successfully"
}

{
  "success": true,
  "data": { "pspReference": "PSPREF_EXAMPLE_456", "status": "received" },
  "message": "Refund processed successfully"
}

GET `/v1/payments/refundable-amount/{id}`

curl "https://payments.valpay.com/v1/payments/refundable-amount/TXN_EXAMPLE_001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://payments.valpay.com/v1/payments/refundable-amount/TXN_EXAMPLE_001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://payments.valpay.com/v1/payments/refundable-amount/TXN_EXAMPLE_001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200 (illustrative):

{
  "success": true,
  "data": { "refundableAmount": { "value": 1599, "currency": "USD" } },
  "message": "Refundable amount retrieved successfully"
}

{
  "success": true,
  "data": { "refundableAmount": { "value": 1599, "currency": "USD" } },
  "message": "Refundable amount retrieved successfully"
}

{
  "success": true,
  "data": { "refundableAmount": { "value": 1599, "currency": "USD" } },
  "message": "Refundable amount retrieved successfully"
}

POST `/v1/payments/void`

curl -X POST https://payments.valpay.com/v1/payments/void \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 2599, "currency": "USD" }
  }'

curl -X POST https://payments.valpay.com/v1/payments/void \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 2599, "currency": "USD" }
  }'

curl -X POST https://payments.valpay.com/v1/payments/void \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN_EXAMPLE_001",
    "amount": { "value": 2599, "currency": "USD" }
  }'