Primer

Primer is an EMEA and APAC-focused payment orchestrator that primarily serves medium to enterprise merchants.

Supported payment methods: Cards, Apple Pay, and Google Pay. For more details, see the Payment methods overview.

Prerequisites

Before you begin, make sure you have:

• An existing Airwallex account. You can find your Airwallex API key and Client ID in the Airwallex web app under Account > Developer.
• Airwallex configured in the Primer integrations page.

Add Airwallex as the payment gateway

You can add Airwallex as the payment gateway in Primer to process card transactions. Follow these steps to complete your configuration:

1. Create an Airwallex account by submitting your business information. If you don't have an account yet, contact us directly.
2. Activate the payment methods you want to accept. The integration currently supports cards, Apple Pay, and Google Pay.
3. In the Airwallex web app under Account > Developer, copy your Client ID, then select Create restricted API key. Enter a name, select the Payment Acceptance and Finance access scopes, then select Create API Key and copy the scoped API key. For more information, see Scoped API keys.
4. Request that your account be exempt from Airwallex internal 3DS. Ask your account manager to arrange this, as it is required for successful transactions. If you want to enable 3DS, integrate with Primer's 3DS solution.
5. Add the device fingerprinting script to your checkout site:
   • Load the Airwallex JavaScript on your checkout page to collect device data by following steps 1 and 2 in the device fingerprinting guide, where the data-order-session-id value is unique.
   • Pass the data-order-session-id value to Primer in the device_id field, as part of gateway_specific_field, in the Authorization and Purchase transactions.

Set up metadata mapping in Primer

Prepare the metadata mapping

In the Primer dashboard, open the existing integration and select Advanced mapping. Add the fields you want Primer to map from your incoming metadata payload to the downstream Airwallex request. Primer supports multiple mapped fields and nested metadata structures. Use dot notation when the source value sits inside nested objects.

A practical approach is to separate metadata into logical groups, such as customer_data, order_data, risk_data, and merchant_defined_data. For example, you might configure these source paths in Primer:

• metadata.customer_data.customer_ip_address
• metadata.order_data.order_reference
• metadata.risk_data.device_id

The destination field names should match Airwallex's downstream expectations.

Send the metadata in the payment request

After the mapping is configured, pass the required metadata either in the client session, if the payment is made through Universal Checkout, or directly in the payment request. Primer's example payload shows metadata structured as nested JSON objects under metadata:

1{
2  "orderId": "order-123",
3  "amount": 3000,
4  "currencyCode": "GBP",
5  "customerId": "cust-123",
6  "metadata": {
7    "customer_data": {
8      "customer_ip_address": "127.0.0.1"
9    },
10    "my_additional_data": {
11      "field_1": "foo",
12      "field_2": "bar"
13    },
14    "some_unmapped_field": 123
15  }
16}

Validate the downstream mapping result

Once the request is sent, confirm that the mapped fields appear in the request Primer sends to Airwallex. Check that:

• the mapped fields are populated with the expected values,
• nested fields resolve correctly,
• unmapped fields are ignored unless explicitly configured, and
• data types are preserved as expected.

Recommended approach

• Map two or three critical fields first.
• Test with a non-production payment flow.
• Inspect the downstream Airwallex request.
• Add further fields only after the base mapping is verified.

The following table shows example metadata groups:

Settlement report and reconciliation

You can download the settlement reports for reconciliation from the web app > Reports page. See Settlement reports for more details.