This section provides reference information about payment transactions. Every payment request in the API will generate a new Transaction.

📘
Note
Each Transaction is uniquely identified by a CURO Transaction ID (transaction_id): TYYM12345678

T from "Transaction"

YY year number

M month as hexadecimal (1-9, A=10, B=11, C=12)

12345678 8 digit unique number
The total length is always 12 characters.

You are required to provide a Transaction Reference (reference) to identify this transaction in your own system.
Please see Transaction Flow for a schematic overview of the standard transaction processing.

Transactions can have several status codes during their lifetime; the complete list of Status Codes is shown below. A Transaction is considered to be "Completed" (final) if the status code is in the 2XX range (200 or 210 mostly).

📘
Note

It is technically possible to create multiple transactions for the same Transaction Reference (reference).

Please make sure your system can handle this correctly, for example by ignoring multiple notifications for the same reference if the transaction has already been completed (i.e. a 2XX code has been received).

REST request

Entry point: /rest/v1/curo/payment/<chosen payment method>/

`[request]` container — generic items

Field name	Type Length	Required	Description
`site_id`	integer ≤ 10	required	Merchant's site ID.
`url_success`	string ≤ 255	required	Valid return URL beginning with http:// or https:// where a consumer will be redirected after payment.
`url_pending`	string ≤ 255	optional	Optional return URL for pending payments. The `url_success` will be used if not specified.
`url_failure`	string ≤ 255	required	Return URL for failed payments.
`url_cancel`	string ≤ 255	optional	Optional return URL for cancelled payments. The `url_failure` will be used if not specified.
`url_callback`	string ≤ 255	recommended	URL which will receive transaction updates automatically; please check Callback for more information.
`reference`	string ≤ 255	required	Unique merchant identification for a transaction.
`amount`	integer ≤ 10	required	The amount in cents (with no decimal separator).
`currency_id`	string 3	required	Currency in which payment should be effected, expressed using the three-letter international currency code as per ISO-4217.
`description`	string ≤ 128	required	Transaction description which will be presented to the user if supported by the payment method. (Maximum length for iDEAL is 32 characters. For credit card always uses a fixed descriptor on the consumer's card statement.)
`info`	string ≤ 255	required	Extra information to store with the transaction.
`ip`	string ≤ 40	required	Consumer's IP address. Although IPv6 is supported by CURO, most payment methods (still) don't support it.
`country_id`	string 2	optional	ISO country code of the consumer.
`language_id`	string 2	optional	Consumer's preferred language. Possible options: Czech (cz), Croatian (hr), Danish (da/dk), Dutch (nl), English (en) default, French (fr), Finnish (fi), German (de), Greek (gr), Hungarian (hu), Italian (it), Norwegian (no), Polish (pl), Portuguese (pt), Russian (ru), Spanish (es), Swedish (se), Turkish (tr).

📘
Consumer information for this transaction.

`[consumer]` container — generic items

Field name	Type Length	Required	Description
`firstname`	string ≤ 32	required (default)	Consumer's first name.
`initials`	string ≤ 64	required for some methods (e.g. Afterpay, Klarna)	Consumer's initials.
`lastname`	string ≤ 64	required (default)	Consumer's last name.
`gender`	string 1	required for some methods (e.g. AfterPay)	Consumer's gender (`F` or `M`).
`dob`	string ≤ 10	required for some methods (e.g. Klarna)	Consumer's date of birth (`YYYYMMDD` or `DD-MM-YYYY`).
`ssn`	string ≤ 64	required for some methods (e.g. Klarna)	Consumer's social security number.
`company`	string ≤ 64	optional	Consumer's company name.
`address`	string ≤ 128	optional	Consumer's address.
`city`	string ≤ 128	optional	Consumer's city.
`state`	string ≤ 32	optional	Consumer's state.
`zipcode`	string ≤ 16	optional	Consumer's postal code.
`country_id`	string 2	optional	Two letter country code of a consumer, according to ISO-3166.
`phone`	string ≤ 16	optional	Consumer's phone number.
`email`	string ≤ 64	required (default) / recommended	Consumer's email address.
`agent`	string ≤ 255	recommended	Consumer's User-Agent string. Recommended for recurring/card-on-file payments.
`referer`	string ≤ 255	recommended	Optional referrer URL for your own reference. Recommended for recurring/card-on-file payments.

📘
Shipping information for this transaction.

Shipping fields (within `[consumer]`)

Field name	Type Length	Description
`shipto_firstname`	string ≤ 32	Ship to first name.
`shipto_initials`	string ≤ 64	Ship to initials.
`shipto_lastname`	string ≤ 64	Ship to last name.
`shipto_gender`	string ≤ 64	Ship to gender (`F` or `M`).
`shipto_dob`	string ≤ 64	Ship to date of birth (`YYYYMMDD` or `DD-MM-YYYY`).
`shipto_company`	string ≤ 128	Ship to company.
`shipto_address`	string ≤ 128	Ship to address.
`shipto_city`	string ≤ 128	Ship to city.
`shipto_state`	string ≤ 32	Ship to state.
`shipto_zipcode`	string ≤ 16	Ship to postal code.
`shipto_country_id`	string 2	Two letter country code of a consumer, according to ISO-3166.

📘
The cart items of the webshop order. Each cart item is wrapped in an [item] sub container (XML only).

`[cartitems]` container — generic items

Field name	Type Length	Required	Description
`quantity`	integer ≤ 5	optional	Quantity. `1` is used if no value is specified.
`sku`	string ≤ 64	required	Article number / Stock Keeping Unit.
`name`	string ≤ 64	required	Article name / description.
`price`	integer ≤ 10	required	Article price per item in cents.
`vat`	numeric ≤ 10,2	required	VAT percentage.
`vat_amount`	integer ≤ 10	recommended	VAT amount included/excluded in the price per item in cents. NB when omitted it will be calculated automatically; however for prices excluding VAT, rounding errors may occur which can lead to transaction failure for Klarna or Afterpay.
`vat_inc`	boolean 1	optional	Specify whether prices are in- or excluding VAT: `0` excluding VAT (default), `1` including VAT.
`type`	integer 1	optional	Type of item: `1` normal product (default), `2` shipping costs, `3` administrative costs (not used by Klarna), `4` discounts, `5` handling costs.
`stock`	integer ≤ 5	optional	Amount in stock for this article. Specify this to prevent auto-capture of an order if items are out of stock. NB completely omit this parameter if you don't want or need stock checking; otherwise the stock value might become `0` and prevent auto-captures.

REST response elements

📘
Note

The exact response details depend on the chosen payment method (if one is indicated); please check the appropriate module documentation for more information.

Field name	Type Length	Description
`[payment]`	container	General container for this resource.
`transaction_id`	string ≤ 12	Newly created transaction ID.
`url`	string ≤ 255	Complete URL to which the consumer must be redirected to complete the transaction. (1) Depending on the provided information and payment method, you will also receive a URL if the provided information was invalid or incomplete; in that case the URL will point to the default payment gateway page. (2) It is your responsibility to redirect the consumer to the provided `url` address.

Transaction Details

Entry point: /rest/v1/curo/transaction/<transaction_id>

To verify whether a transaction was successful, send a transaction detail GET request to the API. This can be done after the consumer returns to the merchant's website (after the redirect from the payment method), or after a specified amount of time (for example 5 or 10 minutes from starting the payment transaction).

⚠️
Important
To avoid unnecessary system load it is recommended not to repeat the status request every minute, and to minimize the status request after a certain period of time.
Reminder: It is highly recommended to use the Callback option via url_callback. You can pass it dynamically for each transaction or enter a fixed URL in the Merchant Backoffice. The URL will automatically receive transaction status updates so you don't need to set up a custom status request procedure.

REST response elements

Field name	Type Length	Description
`[transaction]`	container	General container for this resource.
`id`	string ≤ 12	Transaction ID.
`merchant_id`	integer ≤ 10	Merchant's ID.
`site_id`	integer ≤ 10	Merchant's site ID.
`site_name`	string ≤ 10	Merchant's site name.
`code`	integer ≤ 3	Status code of the transaction.
`country_id`	string 2	Country code.
`currency_id`	string 3	Transaction currency.
`amount`	integer ≤ 10	The amount in cents (with no decimal separator).
`reference`	string ≤ 255	Unique merchant identification for a transaction.
`parent_transaction_id`	string ≤ 12	Unique transaction_id, or 'master' when it's a single payment.
`payment_type_id`	integer ≤ 2	ID of the payment type.
`payment_type`	string ≤ 32	Name of the payment type.
`option`	string ≤ 32	Gateway option used for this transaction.
`type`	string ≤ 32	Type of the payment (e.g. payment, refund, etc.).
`description`	string ≤ 32	Description for this transaction.
`tinfo`	string ≤ 255	Additional transaction information from the payment method. May be null.
`testmode`	string 1	Whether the transaction is in test mode.
`ip`	string ≤ 15	IP address of the consumer.
`registered`	string ≤ 19	Registration time of the transaction, in 'YYYY-MM-DD HH:MM:SS' format (Europe/Amsterdam).
`updated`	string ≤ 19	Last update time of the transaction, in 'YYYY-MM-DD HH:MM:SS' format (Europe/Amsterdam).
`finished`	string ≤ 19	Whether the transaction is finished.

📘
Consumer associated with this transaction, which was sent to the API earlier for this transaction.

`[consumer]` (response) — optional

Field name	Type Length	Description
`firstname`	string ≤ 32	Consumer's first name.
`lastname`	string ≤ 64	Consumer's last name.
`name`	string ≤ 96	Consumer's first and last name combined.
`company`	string ≤ 64	Consumer's company name.
`address`	string ≤ 128	Consumer's address.
`street`	string	Consumer's street (separated address).
`housenumber`	string	Consumer's housenumber (separated address).
`city`	string ≤ 128	Consumer's city.
`zipcode`	string ≤ 16	Consumer's postal code.
`country_id`	string 2	Two letter country code of a consumer, according to ISO 3166.
`phone`	string ≤ 16	Consumer's phone number.
`email`	string ≤ 64	Consumer's email address.
`shipto_firstname`	string ≤ 32	Ship to first name.
`shipto_initials`	string ≤ 64	Ship to initials.
`shipto_lastname`	string ≤ 64	Ship to last name.
`shipto_gender`	string ≤ 64	Ship to gender.
`shipto_dob`	string ≤ 64	Ship to Date Of Birth.
`shipto_company`	string ≤ 128	Ship to company.
`shipto_address`	string ≤ 128	Ship to address.
`shipto_city`	string ≤ 128	Ship to city.
`shipto_state`	string ≤ 32	Ship to state.
`shipto_zipcode`	string ≤ 16	Ship to postal code.
`shipto_country_id`	string 2	Two letter country code of a consumer, according to ISO 3166.

📘
Optional: Payout details if this option is enabled for the Merchant. Will contain multiple items.

`[payouts]`

Field name	Type	Description
`payout_type_id`	integer	Internal payout type identifier (see list below). ID Description 1 Processed payment (full consumer amount) 2 Transaction costs 3 (Rolling) Reserves 4 Reserves payout 5 Referral fee 6 Refund buffer 7 Processed payments (correction) 9 Refund fee 10 Refund 11 Failed transactions fee 18 Processed payments (distributing) 19 Transaction costs (distributing) 24 Chargeback fee 25 Chargeback 26 Reseller commission 28 Transaction costs (correction) 29 Anti-fraud check 30 SMS fee
`type_description`	string	Textual payout type description.
`currency`	string	Payout currency (3 char ISO code).
`amount`	numeric	Payout amount in cents. Will be negative for fees!
`due_date`	date (YYYY-MM-DD)	Scheduled payout date. Usually the same day, but some payment methods (credit card, OU) have a delay.
`invoice_number`	string	Number of the invoice the payout/fee is on. Assigned when the payout is picked up by a payout-run (usually on Mondays and Thursdays). Each run will create a Statement, Invoice, and a Settlement. Statement (`SYYM.<merchant-id>.123456789`) = gross consumer transaction amount to be paid out. Invoice (`CYYM.<merchant-id>.123456789`) = costs and fees. Settlement (`RYYM.<merchant-id>.123456789`) = reconciliation of Statement + Invoice.
`invoice_date`	date (YYYY-MM-DD)	Date of the invoice/statement/settlement (`YYYY-MM-DD`).

📘
Optional: This container contains information from the payment method about this transaction. The exact contents depend on the payment method used.

`[info]` container — optional

Field name	Type Length	Payment method	Description
`cardnumber_masked`	string ≤ 16	Bancontact	Card number (masked).

`reference`	string ≤ 5	Banktransfer	Reference (the value is usually: MANUAL).
`consumer_name`	string ≤ 32	Banktransfer	Consumer's first and last name combined.
`consumer_iban`	string ≤ 32	Banktransfer	Account IBAN number.
`consumer_bic`	string ≤ 10	Banktransfer	Account BIC code.
`book_date`	string ≤ 10	Banktransfer	Book date of the transaction.
`recipient_name`	string ≤ 32	Banktransfer	(Company) Name of the recipient.
`recipient_iban`	string ≤ 20	Banktransfer	Account IBAN number of the recipient.
`recipient_bic`	string ≤ 10	Banktransfer	Account BIC code of the recipient.

`result_code`	integer ≤ 5	Credit card	Result code, where `0` is OK, otherwise it is the error code.
`card_holder` / `account_name`	string ≤ 32	Credit card	Card holder's name.
`card_issuer`	string	Credit card (optional)	Card issuer name.
`card_type`	string	Credit card (optional)	Card type.
`card_expiry`	date (YYYY-MM-DD)	Credit card (optional)	Card expiry date (day is always 01).
`account_number`	string ≤ 16	Credit card	Account number (masked).
`card_brand`	string ≤ 32	Credit card	Credit card brand.
`card_secure`	string ≤ 3	Credit card	Indicates whether transaction is 3D-Secure (`Yes` / `No`). The value between parentheses means: U = unknown, Yes = merchant is liable, No = issuer/bank is liable. XML example: `<card_secure>No (U)</card_secure>`.

`mandate_id`	string ≤ 12	DirectDebit	Mandate id.
`mandate_date`	string ≤ 10	DirectDebit	Mandate date.
`consumer_name`	string ≤ 32	DirectDebit	Consumer's first and last name combined.
`consumer_iban`	string ≤ 32	DirectDebit	Account IBAN number.
`consumer_bic`	string ≤ 10	DirectDebit	Account BIC code.
`book_date`	string ≤ 10	DirectDebit	Book date of the transaction.
`execute_date`	string ≤ 10	DirectDebit	Execute date of the transaction.
`sequence_type`	string ≤ 4	DirectDebit	Sequence type.
`recipient_name`	string ≤ 32	DirectDebit	(Company) Name of the recipient.
`recipient_iban`	string ≤ 20	DirectDebit	Account IBAN number of the recipient.
`recipient_bic`	string ≤ 8	DirectDebit	Account BIC code of the recipient.
`recipient_identifier`	string ≤ 20	DirectDebit	Identification code of the recipient.

`issuer`	string ≤ 32	iDEAL	iDEAL Issuer/Bank.
`ideal_ref`	string ≤ 32	iDEAL	iDEAL reference.
`consumer_name`	string ≤ 32	iDEAL	Consumer's first and last name combined.
`consumer_iban`	string ≤ 32	iDEAL	Account IBAN number.
`consumer_bic`	string ≤ 10	iDEAL	Account BIC code.

`token`	string ≤ 32	PayPal	Unique transaction ID (Token).
`first_name`	string ≤ 32	PayPal	Consumer's first name.
`last_name`	string ≤ 32	PayPal	Consumer's last name.
`email`	string ≤ 32	PayPal	Consumer's email address.
`country_id`	string 2	PayPal	Country code.

`error_code`	integer ≤ 3	Przelewy24	Error code, where `0` is OK, otherwise it is the error code.
`error_messages`	string ≤ 32	Przelewy24 (optional)	Short description of the error.
`token`	string ≤ 32	Przelewy24 (optional)	Unique transaction ID (Token).
`email`	string ≤ 32	Przelewy24	Consumer's email address.
`order_id`	string ≤ 32	Przelewy24	Transaction number received from Przelewy24.
`method`	integer ≤ 2	Przelewy24	Payment method ID used by the Client.

`reference`	integer ≤ 5	Sofort	Reference from Sofort.
`description`	integer ≤ 5	Sofort	Your own description.
`consumer_name`	string ≤ 32	Sofort	Consumer's first and last name combined.
`consumer_iban`	string ≤ 32	Sofort	Account IBAN number.
`consumer_bic`	string ≤ 10	Sofort	Account BIC code.
`bank_code`	integer ≤ 5	Sofort	Bank code.
`book_date`	string ≤ 20	Sofort	Book date of the transaction.

Transaction detail request — example

JSON request

GET /rest/v1/curo/transaction/T26123456789/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Host: secure.curopayments.net
Accept: application/json

JSON response

{
    "success": true,
	  "transaction": {
			"merchant_id": "1234",
			"site_id": "1234",
			"site_name": "Test Site",
			"code": "200",
			"country_id": "NL",
			"currency_id": "EUR",
			"amount": "100",
			"reference": "O1234567890",
			"parent_transaction_id": null,
			"payment_type_id": "18",
			"payment_type": "iDeal",
			"option": "idealpro",
			"type": 1,
			"description": "Order 1",
			"tinfo": null,
    	"testmode": "0",
    	"ip": "1.2.3.4",
    	"registered": "2026-07-27 09:30:00",
    	"updated": "2026-07-27 09:30:31",
    	"finished": "2026-07-27 09:30:31",
		"info": {
			"issuer": null,
			"ideal_ref": "0050000110234217",
			"consumer_name": "Hr E G H K\u00fcppers en\/of MW M.J. K",
			"consumer_iban": "NL53INGB0654422370",
			"consumer_bic": "INGBNL2A"
		},
		"consumer": {
			"name": "Joe Doe",
			"firstname": "Joe",
			"lastname": "Doe",
			"email": "[email protected]",
			"address": "nowhereroad 12",
			"street": "nowhereroad",
			"housenumber": "12",
			"city": "NonVille",
			"zipcode": "12345",
			"country_id": "NL",
			"phone": "1234567890",
			"account_name": "Hr E G H K\u00fcppers en\/of MW M.J. K\u00fcppers-Veeneman",
			"account_number": "NL53INGB0654422370",
			"account_code": "INGBNL2A",
			"user_agent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Mobile Safari/537.36"
		},
		"payouts": [
            {
                "payout_type_id": "2",
                "type_description": "Transaction costs",
                "currency": "EUR",
                "amount": "-45.00",
                "due_date": "2026-07-27",
                "invoice_number": null,
                "invoice_date": null
            },
            {
                "payout_type_id": "1",
                "type_description": "Processed payments",
                "currency": "EUR",
                "amount": "100.00",
                "due_date": "2026-07-27",
                "invoice_number": null,
                "invoice_date": null
            }
        ],
        "can_refund": true,
        "refund_remainder": 100,
        "refund_extra_limit": 0,
		"id": "T26123456789"
	}
}

Transaction Capture, Cancel, Recurring, Refund

These operations are documented in the corresponding sections of the CURO API reference:
Generic Capture,
Generic Cancel,
Generic Recurring/SEPA,
Generic Refund,
Generic Void.

See the source documentation for full details.

Transaction Status Codes

A transaction is considered "Completed" (final) when the status code is in the 2XX range (typically 200 or 210).

Newly created transactions will initially have a status code of 0. Depending on the payment method the status will be updated to reflect the current status. Every update to the transaction is registered in the Transaction History (visible in the backoffice).

The global status code ranges are:

0 - pending; waiting for acquirer.
1XX - authorisation phase 1 codes (credit card).
2XX - transaction completed successfully.
3XX - transaction failed.
4XX - refunds and reversals. These codes will be linked to a separate Refund/Chargeback/Reversal transaction.
6XX - informational code for fraud or retrieval notifications. These codes will only be visible in Transaction History.
7XX - waiting for confirmation or receiving of the transaction.

List of Status Codes

Status Code	Description
0	Transaction in progress
100	Authorization successful
120	Authorisation cancelled
130	Authorisation failed
140	Authorisation rejected
150	3D secure status 'Y' (yes), waiting for 3D secure authentication
152	3D secure status 'N' (no)
154	3D secure status 'U' (unknown)
156	3D secure status 'E' (error)
200	Transaction successful
210	Recurring transaction successful
220	Authorisation successful
300	Transaction failed
301	Transaction failed due to anti fraud system
302	Transaction rejected
303	3DS declined
305	Do not honour
308	Transaction was expired
309	Transaction was cancelled
310	Recurring transaction failed
330	Authorization failed
333	Card expired
334	Suspicion of manipulation
341	Lost card (was reported lost by owner)
343	Hot card (known fraud with this card)
344	Pickup card (card is flagged/blocked)
350	Transaction failed, time-out for 3D secure authentication
351	Transaction failed, non-3DS transactions are not allowed
352	Transaction failed 3DS verification
370	Wait time expired
399	Acquirer request error
400	Refund to consumer
404	Reversal by system (transaction was never received or bounced)
410	Chargeback by consumer
412	Chargeback reversal
420	Chargeback (2nd attempt)
450	Authorization cancelled
700	Transaction is waiting for user action
701	Waiting for capture
702	Waiting for execution date
710	Waiting for confirmation recurring
750	Waiting for confirmation (from external party like a bank)
751	Underpaid, waiting for merchant action

Note

Note

REST request

[request] container — generic items

[consumer] container — generic items

Shipping fields (within [consumer])

[cartitems] container — generic items

REST response elements

Note

Transaction Details

Important

REST response elements

[consumer] (response) — optional

[payouts]

[info] container — optional

Transaction detail request — example

JSON request

JSON response

Transaction Capture, Cancel, Recurring, Refund

Transaction Status Codes

List of Status Codes

`[request]` container — generic items

`[consumer]` container — generic items

Shipping fields (within `[consumer]`)

`[cartitems]` container — generic items

`[consumer]` (response) — optional

`[payouts]`

`[info]` container — optional