Getting Started

What It's For

Integrate to the Commerce Suite AR Module to sync receivables documents such as invoices, orders, or quotes to seamlessly collect payments against them through Commerce Suite's robust hosted payments engine.

How It Works

1. Define all receivables document types that are to be enabled in Commerce Suite.
2. Sync merchant receivables documents (Invoice, Sales Order, etc.) for which payment will be collected through Commerce Suite.
3. Update previously synced documents to manage things like date, tax, or balance adjustments on-the-fly.
4. Query any document to retrieve a live payment URL or simply direct end-users to the Commerce Suite portal to make a payment against any synced document.

Key AR Endpoints

Obtain an API Token:

• POST /api/Authorize with your AR-Specific username and password to receive a token. This token should then be securely stored and included in the Authorizationheader for all AR related requests.

Define Merchant Document Types:

• POST /api/MerchantPlatformDocType entity to specify the types of documents (e.g., Invoice, Sales Order, Quote) you want to present to paying customers. At least one type is required.

Create and Manage Payors (Customers):

• POST /api/MerchantCustomerCard to create a MerchantCustomer.
• PUT /api/MerchantCustomerCard to update the customer.
• DELETE /api/MerchantCustomerCard/:merchantCustomerCardId a customer by ID.

Create and Manage Enabled Doc Types:

• POST /api/Document to create a new document record for the indicated document type.
• GET /api/Document/{documentID/customerId} to retrieve documents by customer or doc Id.
• PUT /api/Document/{documentId} to edit an existing document to updates things like dates, tax amount, freight, current balance, and attached PDF documents.
• DELETE /api/Document/{documentId} to delete an existing document by documentId.

What It's For

How It Works

1. Use the endpoints below to create, update, or retrieve bills tied to vendors.
2. Configure payout options (ACH, Check, RTP) for each merchant gateway before initiating disbursements.

Key AP Endpoints

Obtain a Commerce Suite API Token

• POST /api/Authorize with the gateway credentials that you'll be using for AP to receive an access token. Then, securely store this token for use in the Authorization header for all AP operations.

Create and Track Vendor Bills:

• POST /api/Bill to create a new vendor bill that you would like to track in Commerce Suite.

Make Updates to Vendor Bills:

• PUT /api/Bill to make adjustments or updates to an existing bill.

Delete Previously Synced Vendor Bills:

• DELETE /api/Bill?id={billId} to delete a bill by billId.

List All Synced Vendor Bills:

• GET /api/Bill/All to get a list of all bills available for this merchant.

Fetch a Bill by Bill Id

• GET /api/Bill/{billId} to retrieve a specific bill by billId.

Configure Commerce Suite Vendor Payout

• GET /api/MerchantGatewayPayout to configure merchant payout settings.

Understanding API responses and error handling. Commerce Suite APIs use standard HTTP status codes and always return responses in application/json format. Your integration should check the HTTP status code first, then parse the response body for additional error or success details.

Common API Response Codes

• 201 Created: The request was successful and a new resource was created.
  Action: Parse the response body for the created resource details.
• 400 Bad Request: The request is not valid (e.g., malformed JSON or missing required fields).
  Action: Check your request for syntax errors or missing/invalid fields. The response body will include details.
• 401 Unauthorized: The credentials or access token are invalid or missing.
  Action: Ensure you are sending a valid access token. Use the /api/Authorize endpoint to obtain one if needed.
• 403 Forbidden: The request does not have permission to access the endpoint.
  Action: Verify your user permissions and endpoint access rights.
• 404 Not Found: The server cannot find the requested resource.
  Action: Check the endpoint URL and resource identifiers.
• 429 Throttle: The server has received more requests than are permitted in one minute.
  Action: Check the error response to determine how long to wait or check merchant settings to adjust the limnit.
• 500 Server Error: The server encountered an unexpected error or may be offline.
  Action: Retry the request again at a later time or contact support if the issue persists.

Best Practices for Error Handling

• Always check the HTTP status code before parsing the response body.
• For 4xx errors, review the error message in the response body for details on what went wrong.
• For 401 and 403 errors, verify your authentication and authorization.
• For 500 errors, consider implementing retry logic and logging the error for further investigation.

Certifying your Commerce Suite integration ensures your ISV solution can securely and reliably support all intended functions in alignment with Nuvei guidelines and best practices. Before production enablement, each Commerce Suite module (e.g. Accounts Receivable or Account Payable) used in your integration must be tested and certified. Below you will find descriptions for the most critical functions to be certified for each Commerce Suite module used.

Account Payable (AP) Functional Certifications

• Authorize: Before making AP calls, you'll need to exchange your AP gateway credentials for a Commerce Suite API token to be used in subsequent AP requests.
• Vendors: Vendors represent your payees. Use vendor endpoints to create, update, and delete vendors in Commerce Suite enabling features such as automated payout routing and vendor self-management.
• Bills: Bills correspond to vendor invoices synchronized from your ERP or created via API. Create, retrieve, update, and delete bills to manage the AP queue prior to payout.
• Payouts: Once bills are approved, create payouts and adjust or cancel them when necessary. For checks, schedule with sufficient lead time to account for printing and mail delivery.
• Additional Certifications: Additional certifications may include configuring payout settings (such as methods and schedules) and retrieving data via OData for reporting or automation.

Account Receivable (AR) Functional Certifications

• Authorize: Before making AR calls, you'll need to exchange your AR gateway credentials for a Commerce Suite API token to be used in all subsequent API requests.
• Customers: Customers represent the payor. Use customer endpoints to create customer profiles and enable Commerce Suite payments for synced receivable documents.
• Documents: Documents represent transactional receivable items such as invoices, orders, or quotes. Syncing these documents with Commerce Suite allows you to seamlessly collect payments against them through Commerce Suite's robust, hosted payments engine..
• Additional Certifications: Additional certifications may include updating your software platform profile, adjustments to available card types, and other supporting follow up tasks depending on exactly how your integration works.

Sandbox Testing by Gateway

While the Payment Middleware translates transactional production requests across gateways, transaction testing in sandbox environments requires alignment with each gateway's testing practices and test values. This section centralizes the essential test data and scenarios that integrators need across gateways.

Why It Matters

Validating that all payment related activity within Commerce Suite is received, recorded, and (when applicable) settled by your payment gateway protects against mapping errors, field mismatches, or lost webhooks and ensures that what your application sends is exactly what your gateway processes.

Validate using Your Gateway's Reporting / Virtual Terminal (VT)

• Open your gateway's reporting or VT tool and filter by the transaction timestamp window used in testing.
• Search by a reliable key (amount, last 4, reference/transaction ID, order/invoice number, or customer ID).
• Open the gateway detail view and compare each item in “What to Validate” against your middleware request/response records.
• For two-step flows, confirm the relationship: Auth ? Capture (or Sale only) and any subsequent Void/Refund entries are properly linked.
• Confirm settlement (batch close, deposit/funding line) when applicable.

If any value doesn't match: re-check your request body (types, formatting, currency), confirm the correct headers/token were used, and re-run a controlled test with a unique external reference to isolate the entry in reports.

What to validate when checking gateway payment activity

Validation Flow

graph TD
    A[1. API Call to Commerce Suite] --> B(2. CS Processes & Forwards to Gateway);
    B --> C[3. Gateway VT/Reporting];
    A --> D[4. Your API Response Record];
    subgraph 5. Validation Step
        C -.-> E{Compare Records};
        D -.-> E;
    end
    E -- Match --> F[Pass ?];
    E -- Mismatch --> G[Fail ?: Investigate];