GET transactions Request
The GET transactions
request is a “reverse webhook” (meaning, it is triggered by Nuvei not the Marketplace Platform), which is used to retrieve the transactions (order records) from a URL endpoint on the Marketplace Platform’s server.
The request is filtered for a specific processing/reporting period, where the order record date_created
must be between the start_date
and end_date
parameters:
GET /v1/transactions?{start_date}&{end_date}&{seller_id}
Where:
start_date
format – {Year(4)}-{month(2)}-{day(2)}T{Hour(2)}:{Minute(2)}:{Second(2)}Z)end_date
format – {Year(4)}-{month(2)}-{day(2)}T{Hour(2)}:{Minute(2)}:{Second(2)}Z)seller_id
– The ID of the seller in the Marketplace Platform system. (optional)
Example:
Authorization: Basic base64(username:{apiKey}) GET https://DemoMarketplace.com/nuvei/v1/transactions?&start_date=2021-12-07&end_date=2022-02-28
The response contains a list of transactions that were created or updated during this the interval.
transactions
Block
Each of these transactions is presented as a transactions
block that includes the parameters described in the following table:
transactions
Input Parameters
Parameter | Description | Example | Mandatory |
---|---|---|---|
amount | The amount of this transactionType . | 200 | Yes |
currency | The 3-letter ISO currency code. | USD | Yes |
date_created | The payment or the refund request date/time. | 2021-04-12T05:45:39Z | Yes |
last_updated | The date and time when payment_State is changed from PENDING to PAID. | 2021-04-26T05:45:39Z | Yes |
order_id | The value sent as the clientUniqueID in the payment request. (Used for matching.) | 34991440-A | Yes |
order_line_id | Optional field for the use of the Marketplace Platform for internal use. It can have same value as order_id if not used. | 34991440-A | No |
payment_state | The Marketplace Platform sets this field to indicate that the order billing state is:
payment_state = PAID are settled in the current settlement cycle. | PAID | Yes |
payment_batch_number | An optional batchID that a Marketplace Platform can use to assign to any set of transactions, in order to group them on the settlement report. For example, grouping related refund transaction to their order transaction, or for some other internal reconciliation purpose.It is displayed in the settlement report and Marketplace Platform invoice as MarketplaceDocumentNumber . | null | No |
refund_id | The Marketplace Platform ID sent as the clientUniqueID in the refund request. (Used for matching.)Should be null if the transaction_type is not refund related. | null | No |
ExternalSellerId | ID of the seller in the Marketplace Platform system (shop_id from Nuvei Hosted Shop Onboarding). | 1111 | Yes |
ExternalSellerName | Optional; Seller name in the Marketplace Platform system (shop_name from Nuvei Hosted Shop Onboarding). | Seller 1 | No |
transaction_type | Transaction type from the list (see table below). | ORDER_AMOUNT | Yes |
cart_id | Used for mixed carts. | null | No |
Example Response of transactions
Blocks
{ "transactions": [ { "amount": 200.00, "currency": "GBP", "date_created": "2021-04-12T05:45:39Z", "last_updated":"2021-04-26T05:45:39Z", "order_id": "34991440-A", "order_line_id" : "34991440-A", "payment_state": "PAID", "payment_batch_number": null, "refund_id": null, "seller_id": "1111", "seller_name": "Seller 1", "transaction_type": "ORDER_AMOUNT", "cart_id": "34991440" }, { "amount": 16.00, "currency": "GBP", "date_created": "2021-04-12T05:45:39Z", "last_updated":"2021-04-26T05:45:39Z", "order_id": "34991440-A", "order_line_id" : "34991440-A", "payment_state": "PAID", "payment_batch_number": null, "refund_id": null, "seller_id": "1111", "seller_name": "Seller 1", "transaction_type": "COMMISSION_FEE", "cart_id": "34991440" }, { "amount": 4.00, "currency": "GBP", "date_created": "2021-04-12T05:45:39Z", "last_updated":"2021-04-26T05:45:39Z", "order_id": "34991440-A", "order_line_id" : "34991440-A", "payment_state": "PAID", "payment_batch_number": null, "refund_id": null, "seller_id": "1111", "seller_name": "Seller 1", "transaction_type": "COMMISSION_VAT", "cart_id": "34991440" }, ], "total_count": 3 }
transaction_type
Parameter
Each transactions
block includes a transaction_type
which represents “FROM:TO” Accounting Flows.
In the table below, for flows only showing one side, the second side is always the “Nuvei temporary holding account”.
transaction_type
Descriptions
Parameter | Description | Accounting Flows |
---|---|---|
ORDER_AMOUNT (order related) | Order amount (without shipping and tax). | TO Seller |
ORDER_AMOUNT_TAX (order related) | Tax amount for the order. | TO Seller |
ORDER_SHIPPING_AMOUNT (order related) | Order shipping amount (without tax). | TO Seller |
ORDER_SHIPPING_AMOUNT_TAX (order related) | Tax amount for shipping. | TO Seller |
COMMISSION_FEE (order related) | Commission fee amount from the seller. | FROM Seller TO Marketplace Platform |
COMMISSION_VAT (order related) | VAT amount for the commission from the seller. | FROM Seller TO Marketplace Platform |
REFUND_ORDER_AMOUNT (order related) | Refund amount for the order (without tax). | FROM Seller |
REFUND_ORDER_SHIPPING_AMOUNT (order related) | Refund amount for shipping. | FROM Seller |
REFUND_ORDER_AMOUNT_TAX (order related) | Refund amount for the order tax. | FROM Seller |
REFUND_ORDER_SHIPPING_AMOUNT_TAX (order related) | Refund amount for the shipping tax. | FROM Seller |
REFUND_COMMISSION_FEE (order related) | Refund amount for the commission. | FROM Marketplace Platform TO Seller |
REFUND_COMMISSION_VAT (order related) | Refund VAT amount for the commission. | FROM Marketplace Platform TO Seller |
SUBSCRIPTION_FEE (not order related) | Allows the Marketplace Platform to charge the seller with a regular (e.g monthly) subscription fee. | FROM Seller TO Marketplace Platform |
SUBSCRIPTION_VAT (not order related) | Refund VAT amount for the SUBSCRIPTION_FEE . | FROM Seller TO Marketplace Platform |
MANUAL_CREDIT (not order related) | Allows the Marketplace Platform to transfer funds to the seller. Note: This can also be used to return the initial commission to the seller, for a chargeback. | FROM Marketplace Platform TO Seller |
MANUAL_CREDIT_VAT (not order related) | VAT amount for the MANUAL_CREDIT . | FROM Marketplace Platform TO Seller |
MANUAL_INVOICE (not order related) | Allows the Marketplace Platform to charge/retain funds from the seller. Note: This can also be used to charge the seller the initial commission again, for a chargeback reversal. | FROM Seller TO Marketplace Platform |
MANUAL_INVOICE_VAT (not order related) | VAT amount for the MANUAL_INVOICE . | FROM Seller TO Marketplace Platform |
The final amount paid by the customer for an order is the sum of:
ORDER_AMOUNT
ORDER_AMOUNT_TAX
ORDER_SHIPPING_AMOUNT
ORDER_SHIPPING_AMOUNT_TAX
The final amount refunded to the customer for an order is the sum of:
REFUND_ORDER_AMOUNT
REFUND_ORDER_AMOUNT_TAX
REFUND_ORDER_SHIPPING_AMOUNT
REFUND_ORDER_SHIPPING_AMOUNT_TAX