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

Request body (required)

Field	Type	Required	Description
`amount`	`object`	Yes
`store`	`string`	Yes	Store ID
`apiVersion`	`integer`	No	API version number
`reference`	`string`	Yes	Payment reference
`shopperInteraction`	`string`	Yes	Type of shopper interaction
`additionalData`	`object`	No	Additional data for the payment
`paymentMethod`	`object`	Yes
`returnUrl`	`string`	Yes	Return URL after payment
`merchantAccount`	`string`	Yes	Merchant account

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" }
  }'