Airwallex Transactional FX offers a range of flexible solutions that allows our customers to integrate with a solution that best meets their needs when converting currencies. 

Key benefits of the platform include:

- Highly available FX pricing and conversion services - 24 hours a day, 365 days a year.
- Highly competitive pricing - we work hard to offer the best available pricing to all our customers.
- Access to a wide range of currencies - including currencies that are traditionally hard to deal in. 
- Quick and Easy integration - regardless of your choice of product ([__MarketFX__](/transactional-fx__marketfx-overview) or [__LockFX__](/transactional-fx__lockfxfx-overview)), you can be up and transacting quickly from the point of account registration. 


Benefits

Step 2a: Create and connect a connected account for businesses

Using the Scale API you can create Airwallex accounts for the users of your platform or marketplace. Below explains how you can onboard your users if they are individuals without a registered company entity.

There are three main steps to successfully onboard the individuals to Airwallex:

1. Determining and collecting the information/ data required
2. Creating the account
3. Submitting the account for activation

Additionally you need to consider cases where the activation requires additional measures:

4. Handling additional requirements during account activation


1. Determining and collecting the information/ data required

2. Creating the account

3. Submit the account for activation

4. Handling additional requirements during account activation

Step 2b: Create and connect a connected account for individuals

Website QR

Mobile App 

WeChat Official Account

WeChat Mini Program 

Gain access to shoppers on WeChat

Functionalities and value-added features supported

Countries and currencies supported

Choose the integration method that best suits your needs

Accept omni-channel payments from your shoppers with WeChat Pay

WeChat Pay

Payment

Payment with 3D secure

Recurring Payment

Management of payment credentials

Capture

Cancellation

Refund

Customs Declaration

Our native API integration allows you to handle 100% of the front-end and interactions between your front and backend. It is the most suitable if you are PCI-DSS compliant and want to leverage that capability to provide a customized check-out experience to your buyers.


Native API

The Airwallex Customs Declaration functionality enables Merchants who sell goods to mainland China via bonded warehouses to send payment information to China Customs conveniently and safely as regulated. 

Currently, this service supports custom declarations for WeChat Pay transactions that are completed within a year. 


Note

To help you better understand what role Airwallex plays in your declaration process and what functionality our customs declaration API delivers, the Customs Declaration Model below illustrates the major parties in your overall declaration procedures. 
![Illustration - Customs Declaration](//images.ctfassets.net/c3n7jozh84hr/7CpqCUNchbrk2N1OIIbKBG/6f04ee36f9e3bccd43141cb06c495d93/Illustration_-_Customs_Declaration.png)

 1. The customer completes the purchase.

 2. You, as the merchant, shall send custom details and receives payment data via Airwallex Customs Declaration API (see guideline below).

 3. Same as your common practices of completing declaration, it is your responsibility to inform the logistics to send shipment details for declaration, with payment data attached. Also, you need to send order details for declaration, with payment data attached.

 4. After the customs receives all the required information, they will cross-check the detailed information of the order sent by you,  payment methods and logistics. If details matched, customs will agree the merchant to dispatch goods.


Guideline for Customs Declaration

Error handling

The Drop in integration enables Merchants to accept payments when they wish to partially delegate the responsibility of handling their payments but they still aim to control the overall look and feel of their payments page. Note that a limited PCI-DSS certification is required for this integration

The following steps will guide you through our integrations.

 1. Initially you need to create a Payment Intent. The payment intent captures the details of your checkout and includes the currency and amount you wish to charge your customer.

```curl
curl https://pci-api.airwallex.com/api/v1/pa/payment_intents/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token \
  -d '{
    "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
    "amount": 100,
    "currency": "CNY",
    "merchant_order_id": "85d7b0e0-7235-11ea-862e-9f6aa1adfca6"
  }'
```

The response of the Payment Intent creation looks as below and contains a client_secret, it represents your payment session and you need to use it to request the URL where you will redirect your client

 2. In order to leverage the components that Airwallex has built on your behalf, you will need to leverage our frontend scripts.

Load the Airwallex checkout JavaScript in your front end and initialize it accordingly with the information you received.

In order to do so you can get the `airwallex-payment-elements` yarn or npm package

```javascript
yarn add airwallex-payment-elements
```

```javascript
npm install airwallex-payment-elements
```

You can also embed the code directly in your HTML client.

```html

<script src="https://checkout-staging.airwallex.com/assets/bundle.0.0.xx.min.js"></script>
```

Initialize it with
```javascript
// Step #2: Initialize the Airwallex global context for event communication
Airwallex.init({
 env: 'demo', // Setup which env('staging' | 'demo' | 'prod') you would like to integrate with
 origin: window.location.origin, // Setup your event target to receive the browser events message
});
```
Pay attention to the following parameters:
 - env: [Required] setup which env('staging' | 'demo' | 'prod') you would like to integrate with
 - origin: [Required] setup your event target to receive the browser events message

 - options \[Optional\] you can provide additional parameters to customize your checkout following the below interface.

```javascript
/**
* Global font option config for Airwallex integration methods
*/
export interface FontOptions {
 /**
  * The font-family property
  * https://developer.mozilla.org/en-US/docs/Web/CSS/font-family
  */
 family?: string;
 /**
  * The font source url
  * https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face
  */
 src?: string;
 /**
  * The font-weight property
  * https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight
  */
 weight?: string | number;
}
/**
* Indicate which airwallex integration env your merchant site would like to connect with
*/
export type AirwallexEnv = 'dev' | 'preview' | 'qa' | 'staging' | 'demo' | 'prod';
/**
* Global init option config for Airwallex javascript SDK
*/
export interface InitOptions {
 /**
  * Indicate which airwallex integration env your merchant site would like to connect with
  * If not provide default will be prod which point to [Airwallex Checkout](https://checkout.airwallex.com)
  */
 env?: AirwallexEnv;
 /**
  * Your checkout website origin url, aka merchant checkout page's 'window.location.origin' field
  */
 origin?: string;
 /**
  * i18n localization config
  */
 locale?: 'en' | 'zh';
 /**
  * Global font options
  */
 font?: FontOptions;
}
```

 3. It is time to create the elements that will help you to capture the payment details. You can further customize those with the Style interface:

```javascript
/**
* The definition mapping of supported integration element type with it's props options used to customize the element, merchant can check on each element options type for details
*/
export interface ElementOptionsTypeMap {
 /**
  * Define card number input element type and it's mapped option type, apply to split card element integration
  * Using together with `expiry` and `cvc` element to gain maximum customization
  */
 cardNumber: CardNumberElementOptions;
 /**
  * Define expiry input element type and it's mapped option type, apply to split card element integration
  * Using together with `cardNumber` and `cvc` element to gain maximum customization
  */
 expiry: ExpiryDateElementOptions;
 /**
  * Define cvc input element type and it's mapped option type, apply to split card element integration
  * Using together with `cardNumber` and `expiry` element to gain maximum customization
  */
 cvc: CvcElementOptions;
 /**
  * Define W3C payment request API element type and it's mapped option type
  */
 paymentRequestButton: PaymentRequestButtonOptions;
 /**
  * Define card element type and it's mapped option type, this integration make the card PCI input (card number / cvc / expiry) behavior like a single input
  */
 card: CardElementOptions;
 /**
  * Define WeChat element type and it's mapped option type
  */
 wechat: WechatElementOptions;
 /**
  * Define dropIn element type and it's mapped option type, this integration make integrate with Airwallex supported card and APM (alternative payment method like WeChat etc.) payment method like a single widget
  */
 dropIn: DropInElementOptions;
 /**
  * Define full featured card element type and it's mapped option type, this integration make integrate with Airwallex supported card payment method like a single widget
  */
 fullFeaturedCard: FullFeaturedCardElementOptions;
}

/**
* Element integration `step #2`
* Create payment element for checkout
*/
export declare function createElement<T extends ElementType>(
 type: T,
 options?: ElementOptionsTypeMap[T],
): Element | null;
/**
* The payment intent you would like to checkout
* Refer to [Airwallex Client API](https://www.airwallex.com/docs/api#/Payment_Acceptance/Payment_Intents/Intro)
*
* ***Hint***:
* This interface only contain the necessary information when shopper checkout
* For the detail meaning of each field you can refer to above api document
*/
export interface Intent {
 /**
  * Id of intent
  */
 id: string;
 /**
  * client_secret of intent
  */
 client_secret?: string;
 /**
  * Your request id when create payment intent
  */
 request_id?: string;
 amount?: number;
 currency?: string;
 merchant_order_id?: string;
 customer_id?: string;
 status?: string;
 created_at?: string;
 updated_at?: string;
}
 /**
* Supported customized pseudo css style for `cardNumber` | `expiry` | `cvc` elements
* https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes
*/
type PseudoClasses = ':hover' | ':focus' | '::placeholder' | '::selection' | ':disabled';
/**
* Pseudo-classes object
*/
type PseudoClassStyle = { [K in PseudoClasses]?: Properties };

/**
* Customize the the element using CSS properties
* 1. Reference: https://github.com/frenic/csstype
* 2. Extend with element variations for `hpp` | `card` | `dropIn`, following the best practices of https://material-ui.com/api/input-base/
* 3. To support customized Popup overlay width and height
*/
export interface Style extends PseudoClassStyle, Properties {
 /**
  * Input variation for `hpp` | `card` | `dropIn` integration
  */
 variant?: 'outlined' | 'filled' | 'standard' | 'bootstrap';
 /**
  * Customized Popup overlay width like 3DS payment flow
  */
 popupWidth?: number;
 /**
  * Customized Popup overlay height like 3DS payment flow
  */
 popupHeight?: number;
}

/**
* Config options for element integration, support using for ElementType
*/
export interface ElementOptions {
 /**
  * Element css style camelcase option, default style by Chrome browser default
  */
 style?: Style;
 /**
  * Your checkout website origin url, aka merchant checkout page's 'window.location.origin' field
  */
 origin?: string;
}
export interface DropInElementOptions extends ElementOptions {
 /**
  * The payment intent you would like to checkout
  * Refer to [Airwallex Client API](https://www.airwallex.com/docs/api#/Payment_Acceptance/Payment_Intents/Intro)
  *
  */
 intent?: Intent;
 /**
  * The payment method component your website would like to integrate with
  */
 component?: 'default' | 'card' | 'wechatpay';
 /**
  * Indicate whether to capture immediate when authentication success
  */
 autoCapture?: boolean;
 /**
  * Indicate to improve 3DS experience, indicate if the payment form will collect billing info from shopper
  */
 withBilling?: boolean;
}

/**
* Supported integration element type
*/
export type ElementType =
 | 'cardNumber'
 | 'expiry'
 | 'cvc'
 | 'paymentRequestButton'
 | 'card'
 | 'wechat'
 | 'dropIn'
 | 'fullFeaturedCard';

/**
* Functions and external fields can be using in your integration flow with airwallex element
*
* Two ways to get elements, by call createElement function or getElement
*
* ***IMPORTANT***
*
* Once element destroy by call function destroyElement, the element reference should not be using anymore
*/
export interface Element {
 /**
  * Refer to the options when call createElement
  */
 options?:
   | CardElementOptions
   | CardNumberElementOptions
   | ExpiryDateElementOptions
   | CvcElementOptions
   | FullFeaturedCardElementOptions
   | DropInElementOptions
   | WechatElementOptions
   | PaymentRequestButtonOptions;
 /**
  * The iframe element after mount to the DOM
  */
 iframe: HTMLIFrameElement | null;
 /**
  * Refer to the DOM element you call mount function
  */
 domElement: string | HTMLElement;
 /**
  * Element integration `step #3`
  * Mount payment element to your HTML DOM element for checkout
  */
 mount(domElement: string | HTMLElement): void;
 /**
  * Using this function to blur the input html element
  */
 blur(): void;
 /**
  * Using this function to focus the input html element
  * https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/blur
  */
 focus(): void;
 /**
  * Using this function to unmount the element, opposite to mount function
  * https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/focus
  */
 unmount(): void;
 /**
  * Using this function to update the element option after create the element
  */
 update(
   options?:
     | CardElementOptions
     | CardNumberElementOptions
     | ExpiryDateElementOptions
     | CvcElementOptions
     | FullFeaturedCardElementOptions
     | DropInElementOptions
     | WechatElementOptions
     | PaymentRequestButtonOptions,
 ): void;
}

```

Once your customization is complete, you need to create the elements:

```javascript
// Step #3: Create 'dropIn' element
const dropIn = Airwallex.createElement('dropIn', {
 intent: { // Required, dropIn use intent Id and client_secret to prepare checkout
   id: 'replace-with-your-intent-id',
   client_secret: 'replace-with-your-client-secret'
 }
});
// Step #4: Mount 'dropIn' element
dropIn.mount('dropIn');
window.addEventListener('onSuccess', (event) => {
 // Handle event
 alert(JSON.stringify(event.detail));
})
```

The drop-in element will render the available payment methods and enable the customer to select the most applicable for him. Both Local Payment Methods and Card payments are available for the customer to choose.

 4. Place the drop-in element on your checkout page the way suits your website. You  can use the snippet below to fulfill this task

``` javascript
<div id="dropin"></div>
```

Once the element is mounted, the drop-in element will take care of the rest. Upon completion of the checkout (with a success or fail result) you will get an event notification that you must listen to.

 5. You must listen to the events of the drop-in component to appropriately react to those during your checkout. The following interface defines the data you can collect from an event

``` javascript
/**
* Define of error code when failed to validate user input or failed to request
* [Error codes](https://www.airwallex.com/docs/payments__error-codes)
*/
export type ERROR_CODE =
 | 'required'
 | 'invalid'
 | 'un_support'
 | 'expired'
 | 'validation_error'
 | 'duplicate_request'
 | 'resource_not_found'
 | 'resource_already_exists'
 | 'state_invalid_for_operation'
 | 'service_unavailable'
 | 'processor_unavailable'
 | 'processor_busy'
 | 'processor_declined'
 | 'amount_above_limit'
 | 'frequency_above_limit'
 | 'transaction_blocked'
 | 'payment_blocked'
 | 'unsupported_operation_on_payment_method'
 | 'capture_amount_above_limit'
 | 'refund_amount_above_limit'
 | 'insufficient_available_funds'
 | 'insufficient_incoming_funds'
 | 'processor_user_account_abnormal'
 | 'processor_refund_period_expired'
 | 'processor_refund_offline_required';

/**
* Event code supported value by element when shopper interact with the checkout element
*
* `onReady`: The event fires when a given element resource has loaded.
*
* `onSubmit`: The event is raised when confirm the intent. It fires after the click Pay button or calling confirmPaymentIntent function.
*
* `onSuccess`: The event fires when a intent is confirm with Airwallex
*
* `onError`: Error events are fired at various targets for different kinds of errors with shopper interaction, refer to `ElementError` interface.
*
* `onCancel`: The event fires when shopper click cancel button when interact with the payment form.
*
* `onFocus`: The event is raised when the shopper sets focus on an input by click or tab switch interaction.
*
* `onBlur`: The event is raised when an input in element loses focus.
*
* `onChange`: The events fire when the user commits a value change to a input. This may be done, for example, by clicking outside of the input or by using the Tab key to switch to a different input.
*
* `onClick`: The event is raised when the user clicks on an input element.
*
* `onDynamicCurrencyConversion`: The events fire when merchant enable Dynamic Currency Conversion (DCC) feature and shopper is confirm payment with an intent which match DCC scenario
*/
export type EventCode =
 | 'onReady'
 | 'onSubmit'
 | 'onDynamicCurrencyConversion'
 | 'onSuccess'
 | 'onError'
 | 'onCancel'
 | 'onFocus'
 | 'onBlur'
 | 'onChange'
 | 'onClick';

/**
* Return error when failed to validate user input or failed to request
*/
export interface ElementError {
 /**
  * Feel text message in english
  */
 message: string;
 /**
  * String code, will support in the future
  */
 code?: ERROR_CODE;
}

/**
* Event detail, field define by CustomEvent, we fully leverage it to communicate the event payload
*/
export interface EventDetail {
 /**
  * Type of element which fire the event
  */
 type: ElementType;
 /**
  * Indicate if the element input is validate format
  */
 complete?: boolean;
 /**
  * Indicate if the element input is empty or not
  */
 empty?: boolean;
 /**
  * Indicate the brand of card, only apply for card payment method
  */
 brand?: string;
 /**
  * Indicate the confirm response when integrate with `paymentRequestButton` | `card` | `wechat` | `dropIn` element
  */
 intent?: Intent;
 /**
  * Response error when failed to call interact with shopper input
  */
 error?: ElementError;
}

/**
* The event object your checkout page can listen to by below implementation:
*
* Using html [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent)
*
* window.addEventListener(code: EventCode, (event: { detail: ElementEvent }) => /* Your code here *\/ );
*/
export interface ElementEvent {
 /**
  * Event type code
  * https://developer.mozilla.org/en-US/docs/Web/API/Event/type
  */
 type: EventCode;
 /**
  * Event detail of CustomEvent
  * https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail
  */
 detail: EventDetail;
}

```


```javascript
window.addEventListener('onSuccess', (event) => {
  /*
    ... Your custom to handle success event
  */
}
```

Drop-in integration

Airwallex uses conventional HTTP response codes to indicate the success or failure of an API request. Typically a response code in the 2xx range indicates response, status codes in the 4xx range indicate an error that has been triggered due to the information provided (for example; a parameter does not meet the validation requirements or was not provided), and also for an error with our servers.

HTTP response codes

Error response structure

Response Examples

Error codes for 401, 404

Error codes for 400

Error codes

Airwallex uses [versioning](https://www.airwallex.com/docs/api#/Versioning) to improve our API without affecting the existing users. In this chapter, the API examples as well as the notification event types are all presented in the latest version. For older versions, please refer to our [official API documentation](https://www.airwallex.com/docs/api).

__What’s the existing versions?__

 - 2020-04-30 (latest version)
 - 2019-09-09

__How do I choose the version?__

You may specify the version per API call by setting the __x-api-version__ header. However, in most cases you should rely on the configured version in your account. Overriding version by header is designed for testing and migrating to a new version. 

For webhook notification, you may only specify the expected event version during the webhook creation.


API Versioning

Category codes

Merchant Category Codes

You can [retrieve all transactions](https://www.airwallex.com/docs/api#/Issuing/Transactions/_api_v1_issuing_transactions/get "Get transactions ") associated with an account or for a specific card and also [get one specific transaction by ID](https://www.airwallex.com/docs/api#/Issuing/Transactions/_api_v1_issuing_transactions__id_/get "Get single transaction").

Sample Request

View Transactions Via WebApp

View Transactions

Card management APIs allow you to manage your cards and associated transactions.


Card Cancellation

Card Details Update

Manage Cards

The card object is the resource associated with the card issued by Airwallex. It holds details such as linked accounts and card based spending restrictions and so on. The card object will also allow the client to specify who the card is for (themselves or other entities), card form (physical or virtual), and the number of uses (single or multiple).

To set up a card, use the [Create a card API](https://www.airwallex.com/docs/api#/Issuing/Cards/_api_v1_issuing_cards_create/post "Create Card API") which returns a `card_id`. You would then use this `card_id` to [get card details](https://www.airwallex.com/docs/api#/Issuing/Cards/_api_v1_issuing_cards__id_/get "Get card details").

__Please note:__

1. The Card Object request will not return the full PAN and CVV but will return a Card ID. To get the card details you will need to invoke a [Get sensitive card details](https://www.airwallex.com/docs/api#/Issuing/Cards/_api_v1_issuing_cards__id__details/get "Get sensitive card details") request with the relevant Card ID;
2. To find out the remaining limits for any card under your account, please invoke [Get card remaining limits](https://www.airwallex.com/docs/api#/Issuing/Cards/_api_v1_issuing_cards__id__limits/get "Get card remaining limit") with the relevant Card ID;
3. Issued cards are `Active` and can be used to transact straight away;
4. All Airwallex issued cards are linked to the client’s Airwallex account and funded balancers, so unlike a traditional prepaid product you don't have to lock-in funds on the card when requesting it.





Create a Card via WebApp

Create Cards

The Airwallex Issuing Platform can be used to implement an organization's own consumer cards proposition. By utilizing the Airwallew Bin and along with Airwallex’s Scale and Issuing products, a card can be provisioned for an organisation’s end customer. This card can be topped up via a dedicated collection account specific to that card / cardholder.

In addition, the balance can be extended to hold multiple currencies if required to support a specific use case.

The end customer can be programmatically onboarded including the full KYC process. Access to balance and transaction information is provided by an API enabling a fully native experience to be developed.

1. Via an organisation’s native experience, a card holder can sign up for a Card product providing the relevant proof of identification, and then be instantly provided with a Virtual Card. The physical card can be sent later in the post;
2. At the time of card creation, a unique collection bank account for a desired currency is created and provided to the card holder;
3. The cardholder is told about the card top up account and then move funds to that account;
4. Once funds are available the card can be used;
5. A full view of balance and transaction history is available;
6. Additionally the card can be provisioned to store multiple currencies at the same time either via top up from specific currency collection accounts or by utilizing Airwallex’s FX platform.


Whitelabel Cards

In the insurance industry, speed and control are critical to an end user experience. The Airwallex Issuing platform can be utilized to create this experience.

At the point where an insurance claim is approved, the Insurer can connect to the Airwallex Issuing platform and generate a single use or multi use Virtual card. This card can then be sent to the claimant via their mobile application.

The Virtual card can be locked down to a specific amount and merchant category.

The claimant can visit any service provider who can take card payments (Online or POS), provide the full card details and complete payment for services rendered. Metadata can be associated with cards so as to simplify reconciliation for the Insurer.

Due to Airwallex’s multi currency capabilities the same solution can be rolled in a single country or across a global insurers network.

1. A claim is approved by Insurance assessor in their system;
2. The insurance system requests a single  / multi use Virtual Card for the relevant amount, currency and merchant type via Airwallex API;
3. Airwallex instantly generates a Virtual Card and sends the PAN back to the system via an API response. Virtual Cards are sent out active to the claimant making the transaction process seamless;
4. Claimant uses the Virtual Card details to make a payment with the service provider;
5. Transaction reports are available to support automated reconciliation with the Insurers system.



Automated Insurance Payouts

In the gig economy, contracted staff (Gigster) are looking to be paid quickly, with the payment linked to a job being completed and not on a weekly or monthly cycle.

Utilising Airwallex’s Issuing Platform, a Virtual or Physical card can be generated for a new gigster with funds sent to the card programmatically and in real time when a job is completed. The gigster can then use the card to make payments straight away.

For global organisations funds can be dispersed in a single currency so as to simplify reconciliation activities, Airwallex’s multi currency card will then facilitate local transactions in the currency of the gigsters location.

1. When a gigster is onboarded to the orgsanitions platform they can be provided with a virtual card instantly (a Physical card can follow later in the post);
2. When a job is completed the organization will transfer funds from their master account to the gigster’s card;
3. The funds are available immediately for the gigster to make a payment;
4. Balance and transaction history is available via an API and can be integrated with the gigsters own app experience.


Gig Economy Payroll

Organisations typically have a variety of ongoing payment needs, with a number of payments to be made to suppliers based overseas. These businesses can leverage the Airwallex platform to acquire FX at near interbank rates and then issue cards to payout suppliers in various currencies. You can choose one virtual card for each supplier or for each cost-centre, and set up cards in a way that controls how much is spent and where the card is used.

The savings start when the FX is processed via Airwallex’s market leading FX engine allowing customers access to near interbank rates. When cards are used to payout these funds, there are no hidden fees or charges. 

For the organisations with recurring payment needs, for example monthly subscriptions payments for business software, memberships, recurring office expenses, you can manage your volume by leveraging the Airwallex platform.

1. Organisation requests a multi-use virtual card; sets the allowed currency along with associated transaction limits. The Organisation also nominates the relevant merchant category that is to be allowed, and provides the cost-centre number in the meta-data field;

2. A multi-use Virtual Visa card is generated instantly;

3. The Organisation provides the virtual card details to the supplier via the supplier’s website or platform integration (leveraging the supplier’s payment gateway);

4. As needed (on a recurring basis) the supplier’s gateway initiates a card not present transaction which is routed to Airwallex via the Visa network.






Recurring or Subscription Based Payments

Online Travel Agencies (OTAs) allow customers to book airline tickets, car rentals, hotel rooms and more through an easy to use online interface. Typically, an OTA collects payment from its customers and then makes a payment to the Hotel/Airline via a Global Distribution System (GDS) (such as Amedeus, Galileo).

OTAs (or the GDS nominated by them) can leverage Airwallex Issuing to request one-time use virtual cards through to make these payments. Cards can be set up for a specific amount and currency, along with additional controls such as an allowed merchant category code.

OTA signs up with Airwallex; sets up currency balances in all currencies they require payouts, such as USD, THB, SGD, HKD and so on. They then leverage the Airwallex platform to convert those currencies at near interbank rates.

1. OTA's Customer makes a booking and chooses to pay to the OTA directly (as opposed to the customers paying the hotel directly), the payment is collected from the customers;

2. OTA’s system requests a single use Virtual Card for the relevant amount, currency and merchant type via Airwallex API; 

3. Airwallex instantly generates a Virtual Card and sends the PAN back to the OTA’s system via an API response. Virtual Cards are sent out active to make the transaction process seamless for the OTAs;

4. OTA’s system uses the Virtual Card details to push out the reservation to the GDS;

5. The GDS pushes out the details to the relevant hotel’s property management system (PMS). The hotel's PMS saves card information along with reservation details;

6. When the customer checks out (completes their stay at the hotel), the hotel’s system uses the stored card to generate a transaction, which is routed to Airwallex via the Visa network;

7. Airwallex checks the OTA’s relevant currency account and if there’s sufficient balance in the relevant currency, the transaction is approved and the wallet debited.
![OTA Case study export](//images.ctfassets.net/c3n7jozh84hr/569dExK1l29UemASIgjLAH/bfd099feb094c17fd9c65178280ba999/OTA_Case_study_export.svg)



Online Travel Agencies

Airwallex’s Issuing platform enables businesses to create and manage multi-currency virtual prepaid and debit cards allowing you to unlock the power of the Visa network to pay millions of suppliers globally within seconds.

All Airwallex issued cards are multi-currency and allow you to transact in over 140 currencies supported by Visa, with no international transaction fees, we also offer multiple settlement currencies (Direct Billing).

Airwallex provides a set of RESTful APIs that allows your business to manage their card program. Cards are issued directly to clients to make business-to-business payments quickly, with ease and efficiency.

Airwallex Issuing capabilities support:

1. Provision of Visa prepaid and debit cards (Utilising Airwallex’s principal membership of Visa)
2. Single use or multi use virtual cards
3. Creation of authorisation controls to control the usage of your cards
4. Usage of a single funding source for all cards or seperate sources for each card

As an Airwallex Issuing customer, you don't need to worry about Bin sponsorship, card production, transaction processing or balance management.

Airwallex is fully PCI compliant and depending on your requirements and certifications we can pass full or partial card details to you.




Direct Billing is offered by Airwallex in select G10 currencies (See [Supported Currencies](/issuing__supported-currencies)). What Direct Billing means is that when you transact in these currencies, we can directly debit your Airwallex multi currency account in that currency. No more hidden charges or conversion costs.

Important

Overview

These controls define where the cards may be used. Merchant restrictions can be based on the following levels:

- Merchant Category Code (MCC) – Specifies the MCC where the card can be used. An MCC is a unique identifier for a type of goods or services provided by a set of merchants.
- MCC Group (Coming soon) – Specifies the MCC where the card can be used. An MCC group is a unique identifier for a group of merchant category codes. These groups are provided by Airwallex
- Merchant ID (Coming soon) - Specifies exactly ‘which’ merchant the card can be used by/at

If the Merchant control object is empty then all merchant types are allowed.



Merchant Based Controls

These controls define for which transaction currencies can be processed. You have the option to select specific currencies to be allowed or to allow all currencies leaving the currency control object empty.



Currency Based Controls

Customers can get a list of transactions associated with their account, requested via our API based on a number of parameters for example a specific card, date range, merchant category and so on.

### Sample Request
```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/issuing/transactions?billing_currency=string&card_id=string&from_created_at=to_created_at%20-%2030%20day&page_num=0&page_size=100&retrieval_ref=string&to_created_at=current%20time&transaction_type=string' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0b20iLCJyb2xlcyI6WyJ1c2VyIl0sImlhdCI6MTQ4ODQxNTI1NywiZXhwIjoxNDg4NDE1MjY3fQ.UHqau03y5kEk5lFbTp7J4a-U6LXsfxIVNEsux85hj-Q'
```

Customers can get a list of authorisations associated with their account, requested via our API based on a number of parameters for example a specific card, date range, merchant category and so on.

### Sample Request
```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/issuing/authorizations?billing_currency=string&card_id=string&from_created_at=to_created_at%20-%2030%20day&page_num=0&page_size=100&retrieval_ref=string&status=PENDING&to_created_at=current%20time' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0b20iLCJyb2xlcyI6WyJ1c2VyIl0sImlhdCI6MTQ4ODQxNTI1NywiZXhwIjoxNDg4NDE1MjY3fQ.UHqau03y5kEk5lFbTp7J4a-U6LXsfxIVNEsux85hj-Q'
```

View Authorisations

When an Airwallex issued card is used to make a purchase, an authorization request is initiated by the merchant which reaches Airwallex via the card scheme i.e. Visa and so on.

We will perform a number of checks to ensure that the authorization is genuine and meets any spend controls you had previously set up.

There are two scenarios in which an authorisation request can be received. If we receive a final transaction (called ‘Clearing’) from the merchant we will deduct the requested amount from your balance straight-away.

Sometimes we will receive a pre authorisation request first followed by what is called a ‘clearing’ advice later. In this scenario we will reserve funds with the initial request (These funds will be shown in your reserve balance) and the funds are only deduced fully when the final clearing advice is received. If the merchant does not send the clearing advice in a timely manner (10 days), it is reversed and the funds are released back to you.


Purchase Lifecycle

Airwallex issued cards are multi-currency and can be used for transactions in any currency supported by Visa, as long as you have sufficient balance in your Airwallex account to cover the transaction.
For a transaction in a currency we offer Direct Billing in, we will directly debit your Airwallex multi currency account in that currency without any further hidden charges or conversion fees. For example, for a GBP transaction, your GBP wallet will be debited.
For a transaction in all other currencies, we will debit an equivalent amount from your Base Currency wallet (AUD for Australia). In this case, the conversion rate we use will be based on Visa’s daily rate. For eg, for an AED transaction, your AUD wallet will be debited for an equivalent amount based on Visa's daily rate.



Direct Billing is offered by Airwallex in the following currencies
USD, AUD, CAD, SGD, NZD, HKD, JPY, EUR, GBP, CHF   

Supported Currencies

To make a purchase using Airwallex issued cards, you need to ensure your wallet balances have sufficient funds to use this card. If there are insufficient funds in the corresponding transaction balance then the transaction will be declined. 

You can add funds to the transaction currency balance by either adding funds in your local currency and converting to the transaction currency or adding funds directly to the transaction currency if you have them.


Funding

If clients have reasons to question a purchase made with an issued card, they can dispute it. Please contact your account manager or email support@airwallex.com. We will use the information you provide us and create a dispute request with Visa. The purchase amount is reversed while the dispute process takes place. If the dispute is upheld, this amount is credited back to your account.


Disputes

Transaction Based Controls

You can specify how and where the cards you issue may be used, these rules are called Authorisation Controls. Authorisation Controls are specified when a [new card is requested](https://www.airwallex.com/docs/api#/Issuing/Cards/_api_v1_issuing_cards_create/post "Create Card API") but can also be updated later on.

Airwallex Issuing offers the following types of Authorisation Controls:

1. Currency based controls
2. Merchant based controls
3. Transaction based controls



Control Management in WebApp

Authorisation Controls

These controls allow you to specify spend controls on the card. All Transaction controls are set in a single currency with the transaction being converted to this control currency in realtime. You can select from a number of currencies to be used for Transaction Controls.

Transaction Controls can be:

- Per-transaction: Through this control, you can specify how much you want the card to allow for each transaction in a given currency. This control is especially useful when you set up single-use cards for specific payments
- Daily transaction: Through this control, you can specify the maximum card spend for each day
- Weekly transaction: Through this control, you can specify the maximum card spend for each week
- Monthly transaction: Through this control, you can specify the maximum card spend for each calendar month
- All time: Through this control, you can specify the maximum card spend during its valid period



Reviewing Remaining Spend

Transaction Control Behaviour

Contributing

Payment Acceptance enables new or existing Airwallex Merchants to directly collect money from your consumers through your webshop. Airwallex provides you with payment acceptance capabilities through its payment gateway and partner acquirers domestically in selected regions and for Buyers located anywhere in the globe.

Airwallex Payment Acceptance capabilities are integrated into Airwallex value chain providing you a single integration to get paid by your Buyers, settle the funds in the most suitable currency for you in the Airwallex balance and then repatriate the proceeds to your main country or even leverage those to pay your suppliers in other countries with our Issuance or Payout capability.

Create your Airwallex account by submitting your business information via the [online sign up](https://www.airwallex.com/app/signup?referral=Y29ycHNpdGU%3D) form or by [contacting us](https://www.airwallex.com/contact-sales) directly. Once your account is activated, you will immediately be able to start accepting payment through Airwallex API. We may contact you in case we need further information to complete the onboarding with our partner acquirers.

Take a look at the [Airwallex API](https://www.airwallex.com/docs/api#/) and find out which are the most suitable flows for you or take a look at the Product Acceptance Use Cases to learn how it can help you. Integration can begin immediately following registration success. One of our integration managers will be on hand to guide you through the process of integration, including resolving any queries and helping with testing.

Integrations

Markets and Payment methods 

Starting with Payments

Integration

Customize Usage

Set up Wechat Pay

Features

Examples

The Airwallex iOS SDK is a framework for integrating easy, fast and secure payments inside your app with Airwallex. It provides simple functions to send sensitive credit card data directly to Airwallex, it also provides a powerful, customizable interface for collecting user payment details.

Get started with our integration guide and example project.


iOS Airwallex SDK

Requirements

Native UI

This section mainly introduces the main process of integrating Airwallex Android SDK. This guide assumes that you are an Android developer and familiar with Android Studio and Gradle.

Our demo application is available open source on [Github](https://github.com/airwallex/airwallex-payment-android) and it will help you to better understand how to include the Airwallex Android SDK in your Android project.

Get started with our integration guide and example project.


Android Airwallex SDK

Error Reponse Examples

As you know in order to process cardholder details providers need to be PCI-DSS certified. Airwallex is PCI-DSS certified and in case you require it we can provide you more details.

For you, our Merchant, depending on the integration you use for the Payments business requirements also apply:

 - __API only integration.__ You need to provide during your integration a PCI-DSS AOC and renew it regularly.

 - __Drop-in field integration.__ You need to provide during your integration a PCI-DSS SAQ A-EP questionnaire and renew it regularly according to the specific policy.

 - __Embedded fields integration.__ You need to provide during your integration a PCI-DSS SAQ A-EP questionnaire and renew it regularly according to the specific policy.

 - __Hosted Payments Page integration.__ You need to provide during your integration a PCI-DSS SAQ A questionnaire and renew it regularly according to the specific policy.

Do you need additional information? Visit the [PCI council website](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment)  or contact our support team.

Which PCI-DSS certificate is needed

Airwallex does not provide a separate Transaction Report with all the transactions you have performed in a separate time frame, however if you wish to obtain it use the __Export__ function in the 
[Payment List](/payments__payments). Leverage the filters to select the payments you need. Upon export you have the option to select the fields that are relevant for you.

![transactionlist](//images.ctfassets.net/c3n7jozh84hr/54wYqzTnH8042moKIIDwpl/61625964f30eb9bf3a5c4d134f2a0ab6/image-20200331-085945.png?w=400)


Transaction Report

Create your Airwallex account by submitting your business information via the online sign up form or by contacting us directly. Once your account is activated, you will immediately be able to start accepting payment through Airwallex API. We may contact you in case we need further information to complete the onboarding with our partner acquirers.

Take a look at the Airwallex API and find out which are the most suitable flows for you or take a look at the Product Acceptance Use Cases to learn how it can help you. Integration can begin immediately following registration success. One of our integration managers will be on hand to guide you through the process of integration, including resolving any queries and helping with testing.

When you're ready to begin, you can make your way to our Quickstart guide to get your integration up and running quickly with our series of sample code snippets.

Getting started

Starting with Airwallex Acceptance

At Airwallex we have challenged ourselves to create a transaction model that suits your needs and focuses on what you, our Merchant, cares about.

The main concepts:

- A __Payment Intent__ represents the aim of your Customer to complete its checkout (and of course pay for your services). In it, you find represented Payment transactions, Refunds and if things go bad also Chargebacks.

- A __Payment Attempt__ represents an actual trial to perform a financial transaction. It can be a payment transaction, it can be a refund or even a chargeback. When the customer performs several payment trials before completing the purchase you will have one Payment Attempt for each of the attempts, this way you know what happened and can optimize your checkout. The Payment Attempt tracks each and every individual stage through which the transaction goes.

- A __Financial Transaction__ represents actual and real money. For each Payment Attempt that reaches completion, our platform will generate one or several Financial Transactions. They represent not only the principal amount of your transaction but also the fees associated with it (including gateway fees, interchange fees, markup, etc.), you will have once financial transaction for each of the financial components that are part of a Payment Attempt. Ultimately, only financial transactions will make it to your Airwallex Balance in form or real money.

- Since there will be many Financial Transactions, a __Batch__ groups all the financial transactions that are paid to you (or you have to pay to Airwallex). A Batch will be adjusted for your eventual rolling reserve and will appear as one line in your Airwallex Balance.

Model

Airwallex Payment Acceptance model

Hosted Payment Page integration

Embedded fields integration

Web Integrations

W3C Payment Request API

Getting paid for a one-off payment

Test child page g1p1.1

Test section g1p1s1

Test section g1p1s2

Test page g1p1

Card Management

You can cancel a card for any reason and at any time, and this will prevent any new transactions from being made on this card. However, any transaction that has yet to be cleared will continue to be processed even if the card is cancelled.

### Sample Request
```curl
curl --request POST \
--url 'https://api-demo.airwallex.com/api/v1/issuing/cards/6c2dc266-09ad-4235-b61a-767c7cd6d6ea/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0b20iLCJyb2xlcyI6WyJ1c2VyIl0sImlhdCI6MTQ4ODQxNTI1NywiZXhwIjoxNDg4NDE1MjY3fQ.UHqau03y5kEk5lFbTp7J4a-U6LXsfxIVNEsux85hj-Q' \
--data '{ \
  "card_status": "CLOSED" \
}'
```


If you have access to the Airwallex Webapp then you can also view and manage your cards and transactions there, although our APIs do expose a greater level of control.


WebApp

If you have access to the Airwallex Webapp then you can also view and manage your cards and transactions there, although our APIs do expose a greater level of control.



Card Creation

 You can also create a card from Airwallex WebApp if you have Airwallex account. 


Airwallex’s Foreign Exchange capabilities (FX) provide a wide ranging set of solutions to allow businesses to access FX prices and transaction services in a way that meets the needs and workflows of your business. Each business is unique and the challenges involved with converting one currency to another will also vary from business to business.

The Airwallex solution to these challenges is to offer great flexibility in the way you obtain prices from us, the way you execute transactions with us and the ways that you can manage any inherent FX risk your business is exposed to.

Our two primary products, [__MarketFX__](/transactional-fx__marketfx-overview) and [__LockFX__](/transactional-fx__lockfx-overview) , will allow each business to integrate with the solution that best meets the unique needs of each business. Both products are designed to work closely alongside the wider Airwallex range of features.

If you wish to integrate against the [__Airwallex API__](https://www.airwallex.com/docs/api#/Transactional_FX/Conversion/Intro) , including AirwallexScale , integration can begin immediately following registration success. One of our integration managers will be on hand to guide you through the process of integration, including resolving any queries and helping with testing.

When you're ready to begin, you can make your way to our [__Quickstart__](/transactional-fx__quickstart-guides) guide to get your integration up and running quickly with our series of sample code snippets.



Markdown examples

Alert example

Test page

Airwallex currently has the capability to transact in more than 170 currency pairs across 23 currencies - a capability that is constantly improving. Some of the pairs are freely traded which means we are able to price and execute on both sides of the trade, whereas pairs that contain a currency with additional constraints are considered exotic currency pairs.

### Freely Traded Currencies
The set of freely traded currencies are those that Airwallex can provide pricing and execute on both ‘sides of the trade’, for example on the pair USDHKD, you can:

- Sell USD / Buy HKD
- Buy USD / Sell HKD

The current list of currencies we support include:

- EUR
- GBP
- AUD
- NZD
- USD
- CAD
- CHF
- HKD
- SGD
- CNY (Offshore; sometimes given the code CNH)
- JPY


### Exotic Currencies

The exotic currencies typically have constraints that are applied to them, usually due to regulatory regimes in the local jurisdiction of the exotic currency being transacted.

These constraints may include being able to transact on one side of the trade, as follows for the pair USDMYR:

- Sell USD / Buy MYR

Other constraints may include:

- The need to tie the conversion to an accompanying transfer
- The provision of additional documentation to support the conversion
- Limitations on the conversion date selectable

The current list of currencies we support include:

- THB
- KRW
- IDR
- INR
- PHP
- MYR
- VND
- NPR
- LKR
- PKR
- TRY
- BDT


Currencies

Working closely with your dedicated integration manager, the following LockFX variations can be applied to your account so that the best balance can be struck for your business between __cost__, __speed__ and __matching of commercial workflows__ to the pricing and execution flow selected.

### Quote validity length

Quotes with a range of validity lengths are available via the API. Once a quote is retrieved, then any requests for conversion using that quote must be completed before the expiry time noted on the response. Airwallex is able to support quote validity lengths of:

- 1 minute
- 15 minutes
- 30 minutes
- 1 hour
- 4 hour
- 8 hour
- 24 hour

The default configuration on newly opened Airwallex accounts are validity lengths from the __Short__ group below - *only one group can be assigned per Airwallex account.*
In the event your workflows are better suited to longer validity periods, your integration manager will help to assign your account to a group with longer validity lengths.

| __GROUP__     | __QUOTE VALIDITY LENGTHS__     |
| ---------- | ---------- |
| Short (Default)       | 1 minute, 15 minutes, 30 minutes       |
| Medium       | 30 minutes, 1 hour, 4 hours       |
| Long       | 4 hours, 8 hours, 24 hours       |


### Quote usage

LockFX allows for quotes to be used either multiple times for execution (multi-use), or just once (single-use default) depending on how your account is set-up. This variation will change how you retrieve quotes from Airwallex and use them to execute transactions.


### Refunds

Some clients may have a requirement to initiate a refund, or a reversal of a previously booked and settled transaction at the original rates. Clients looking to access Refunds on their account will need to work closely with their integration manager to understand the volume of expected refunds, and how long following a transaction a refund can be requested, to ensure the best possible pricing can be provided to you.

Refunds can be requested by sending a refund request to the client API quoting the conversion_id of the previously booked and settled conversion you would like a refund on. This will trigger a conversion to be created in the inverse direction of the original conversion. This conversion will need to be funded like any other booked conversion.

### Changing variations

If you wish to change any of the LockFX variations assigned to your account, you will need to contact your integration manager to guide through the process and advise of any changes required to your integration.


LockFX Variations

__Step 1: Check Balance__

Checking the Airwallex Wallet [Balance](https://www.airwallex.com/docs/api#/Core_Resources/Balances/Intro) will allow you to check if you have sufficient funds to complete the conversion immediately.

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
 {
    "available_amount": 10000,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 15000
  },
 {
    "available_amount": 1100,
    "currency": "EUR",
    "pending_amount": 100,
    "reserved_amount": 0,
    "total_amount": 1200
  }
  ```

__Step 2: Retrieve Indicative Quote__

If you are making use of the MarketFX product, you can retrieve an [indicative quote](https://www.airwallex.com/docs/api#/Transactional_FX/Market_FX/_api_v1_marketfx_quote/get) for a specified currency pair that will give you an indication of the current price you would receive if you were to create a currency conversion.

__Sample Request__

```curl
curl -X GET \  'http://api-demo.airwallex.com/api/v1/quotes/market?buy_currency=EUR&sell_currency=USD&buy_amount=500.00&conversion_date=2019-05-21' \
  -H 'Authorization: Bearer <token>'
```

__Response__

```curl
{
    "awx_rate": 1.118012,
    "buy_amount": 500,
    "buy_currency": "EUR",
    "client_rate": 1.119097,
    "sell_amount": 559.55,
    "sell_currency": "USD",
    "conversion_date": "2019-05-21",
    "currency_pair": "EURUSD",
    "dealt_currency": "EUR",
    "settlement_cutoff_time": "2019-05-20T09:00:00+0000"
}
```

__Step 3: Create a new Conversion__

Regardless of whether you have previously retrieved an indicative quote, when you request a [currency conversion](https://www.airwallex.com/docs/api#/Transactional_FX/Conversion/_api_v1_conversions_create/post) it will be executed at the prevailing rate based on market conditions. You do not need to manage quote ids as the request parameters do not allow for an id to be passed.

__Sample Request__

```curl
curl -X POST \
  http://api-demo.airwallex.com/api/v1/conversions/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "request_id": "68726c8c-3ffc-4a54-84ea-e2be08598a29",
  "buy_amount": "500.00",
  "buy_currency": "EUR",
  "sell_currency": "USD",
  "conversion_date": "2019-05-21",
  "term_agreement": true
}’
```

__Step 3a: Create a new Payment__

An alternative to booking a currency conversion and then requesting payments following the processing of that conversion, you can request a [payment](https://www.airwallex.com/docs/api#/Payouts/Payments/_api_v1_payments_create/post) with an underlying currency conversion. To trigger an underlying currency conversion in the payment request, the payment_currency should be different to the source_currency. Again the request parameters do not allow for a quote id to be passed and the currency conversion will be booked at the prevailing rate based on market conditions.

__Sample Request__

```curl
curl -X POST \
  http://api-demo.airwallex.com/api/v1/payments/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "beneficiary": {
    "address": {
      "country_code": "BE",
      "street_address": "55288 Schiller Plain",
      "city": "Port Irvingberg",
      "state": "Iowa",
      "postcode": "88347-1304"
    },
    "bank_details": {
      "bank_country_code": "AU",
      "account_currency": "AUD",
      "account_number": "11111111",
      "account_routing_type1": "bsb",
      "account_routing_value1": "980302",
      "account_name": "Delta Beahan",
      "bank_name": "White Group"
    },
    "entity_type": "PERSONAL",
    "first_name": "Loma",
    "last_name": "Miller",
    "date_of_birth": "1973-04-23"
  },
  "payment_currency": "AUD",
  "source_currency": "EUR",
  "payer": {
    "entity_type": "PERSONAL",
    "address": {
      "country_code": "SI",
      "street_address": "07874 Upton Squares",
      "city": "Willmouth",
      "state": "New Jersey",
      "postcode": "26641-5666"
    },
    "first_name": "Maida",
    "last_name": "Bales",
    "date_of_birth": "1930-04-23"
  },
  "payment_method": "LOCAL",
  "payment_amount": 261,
  "reference": "client-ref",
  "reason": "personal_remittance",
  "request_id": "a07d02b6-0581-441c-a9b6-2997ee3014f3"
}'
```    

__Step 4: Check Balance__

Following a successful conversion, the Airwallex Wallet [Balance](https://www.airwallex.com/docs/api#/Core_Resources/Balances/_api_v1_balances_current/get) will be updated immediately where you have selected to convert today and there were sufficient funds available.

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
 {
    "available_amount": 9440.45,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 14440.45
  },
 {
    "available_amount": 1600,
    "currency": "EUR",
    "pending_amount": 100,
    "reserved_amount": 0,
    "total_amount": 1700
  }
```  

__Step 5: Retrieve the previously created Conversion__

Previously completed conversions can be retrieved and the current status identified on the response. 

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/conversions/d9af1614-a6a1-4d45-aae7-6858fc6d9ede' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
{
  "awx_rate": 0.7815,
  "buy_amount": 10000,
  "buy_currency": "USD",
  "client_rate": 0.7816,
  "conversion_date": "2017-03-22",
  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "created_at": "2017-03-20T10:08:12+1100",
  "currency_pair": "AUDUSD",
  "dealt_currency": "USD",
  "last_updated_at": "2017-03-20T14:00:01+1100",
  "quote_id": "string",
  "reason": "Settling a payment in USD",
  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
  "sell_amount": 12794.27,
  "sell_currency": "AUD",
  "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
  "short_reference_id": "20170608-AF3GJ9",
  "status": "AWAITING_FUNDS"
}
```

MarketFX Quickstart

__Step 1: Check Balance__

Checking the Airwallex Wallet [Balance](https://www.airwallex.com/docs/api#/Core_Resources/Balances/_api_v1_balances_current/get) will allow you to check if you have sufficient funds to complete the conversion immediately.

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
 {
    "available_amount": 10000,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 15000
  }
```

__Step 2: Create a new Quote__

The [quote](https://www.airwallex.com/docs/api#/Transactional_FX/Lock_FX/_api_v1_lockfx_create/post) you retrieve when you are utilising the LockFX product is an executable price as long as it is used before the end of the validity period and the key details from the quote match the subsequent request.

__Sample Request__

```curl
curl -X POST \
  http://api-demo.airwallex.com/api/v1/quotes/lockfx/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
	"buy_currency" : "HKD",
	"sell_currency" : "USD",
	"buy_amount": 67.75, 
	"conversion_date": "2019-05-21",
	"validity": "MIN_15"
}’
```

__Step 3: Store the Quote for future use__

Once you have retrieved your quote, you will need to store the quote_id for future use on subsequent conversion or payment requests. The quote response also contains key details required to ensure a successful subsequent booking including the valid_from and valid_to fields, whether the quote can be used once or multiple times, conversion_date, and the direction (buy/sell currencies). These key details will be validated against the subsequent conversion or payment request.

__Response__

```curl
{
    "quote_id": "995ea163-7652-411d-b37d-ee243c888940",
    "awx_rate": 7.8498,
    "buy_amount": 67.75,
    "buy_currency": "HKD",
    "client_rate": 7.847281,
    "sell_amount": 8.62,
    "sell_currency": "USD",
    "conversion_date": "2019-05-21",
    "currency_pair": "USDHKD",
    "dealt_currency": "HKD",
    "usage": "MULTI_USE",
    "valid_from": "2019-05-20T04:42:19+0000",
    "valid_to": "2019-05-20T04:57:19+0000",
    "validity": "MIN_15"
}
```

__Step 4: Create a new Conversion__

When using LockFX, you must use a valid quote ID in any [conversion](https://www.airwallex.com/docs/api#/Transactional_FX/Conversion/_api_v1_conversions_create/post) or payment request. The relevant details from the quote including buy currency, sell currency and any date if specified must match the subsequent conversion or payment request. A successful conversion request will occur at the client_rate from your retrieved quote.

__Sample Request__

```curl
curl -X POST \
  http://api-demo.airwallex.com/api/v1/conversions/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "request_id": "68f9ee78-b065-422e-8329-62305699ed9e",
  "quote_id": "995ea163-7652-411d-b37d-ee243c888940"
  "buy_amount": "67.75",
  "buy_currency": "HKD",
  "sell_currency": "USD",
  "term_agreement": true,
  "conversion_date": "2019-05-21",
}'
```

__Step 4a: Create a new Payment__

Alternatively, by specifying different payment_currency and source_currency parameters when requesting a [payment](https://www.airwallex.com/docs/api#/Payouts/Payments/_api_v1_payments_create/post), you will trigger an underlying currency conversion. You will need to ensure:
a valid quote_id is passed in the request;
the client_sell_currency from the quote response matches the source_currency in the payment request; and
the client_buy_currency from the quote response matches the payment_currency in the payment request

__Sample Request__

```curl
curl -X POST \
  http://api-demo.airwallex.com/api/v1/payments/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "quote_id": "995ea163-7652-411d-b37d-ee243c888940",
  "request_id": "140ee4b0-18b2-47d9-a823-70ae8f13cb15",
  "beneficiary": {
    "address": {
      "country_code": "BE",
      "street_address": "55288 Schiller Plain",
      "city": "Port Irvingberg",
      "state": "Iowa",
      "postcode": "88347-1304"
    },
    "bank_details": {
      "bank_country_code": "AU",
      "account_currency": "HKD",
      "account_number": "826437792",
      "account_routing_type1": "bsb",
      "account_routing_value1": "980302",
      "account_name": "Delta Beahan",
      "bank_name": "White Group",
      "swift_code": "ACLRAUSS"
    },
    "entity_type": "PERSONAL",
    "first_name": "Loma",
    "last_name": "Miller",
    "date_of_birth": "1973-04-23"
  },
  "payment_currency": "HKD",
  "source_currency": "USD",
  "payment_date": "2019-05-21",
  "payer": {
    "entity_type": "PERSONAL",
    "address": {
      "country_code": "SI",
      "street_address": "07874 Upton Squares",
      "city": "Willmouth",
      "state": "New Jersey",
      "postcode": "26641-5666"
    },
    "first_name": "Maida",
    "last_name": "Tromp",
    "date_of_birth": "1930-04-23"
  },
  "payment_method": "SWIFT",
  "payment_amount": 261,
  "reference": "client-ref",
  "reason": "personal_remittance"
}'
```

__Step 5: Check Balance__

Following a successful conversion, the Airwallex Wallet [Balance](https://www.airwallex.com/docs/api#/Core_Resources/Balances/_api_v1_balances_current/get) will be updated immediately where you have selected to convert today and there were sufficient funds available.

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
 {
    "available_amount": 9991.38,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 14991.38
  },
 {
    "available_amount": 67.75,
    "currency": "HKD",
    "pending_amount": 0,
    "reserved_amount": 0,
    "total_amount": 67.75
  }
```

__Step 6: Retrieve the previously created Transaction Status__

Previously completed conversions can be [retrieved](https://www.airwallex.com/docs/api#/Transactional_FX/Conversion/_api_v1_conversions__conversion_id_/get) and the current status identified on the response. 

__Sample Request__

```curl
curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/conversions/d9af1614-a6a1-4d45-aae7-6858fc6d9ede' \
--header 'Authorization: Bearer <token>'
```

__Response__

```curl
{
  "awx_rate": 0.7815,
  "buy_amount": 10000,
  "buy_currency": "USD",
  "client_rate": 0.7816,
  "conversion_date": "2017-03-22",
  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "created_at": "2017-03-20T10:08:12+1100",
  "currency_pair": "AUDUSD",
  "dealt_currency": "USD",
  "last_updated_at": "2017-03-20T14:00:01+1100",
  "quote_id": "string",
  "reason": "Settling a payment in USD",
  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
  "sell_amount": 12794.27,
  "sell_currency": "AUD",
  "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
  "short_reference_id": "20170608-AF3GJ9",
  "status": "AWAITING_FUNDS"
}
```

LockFX Quickstart

Marketplace platforms connect merchants with large numbers of consumers. They periodically will need to pay Merchants the proceeds of their sales on the platform and these payments can sometimes occur cross-border. 

By coupling the transfer capabilities of the Airwallex API with the best possible pricing from [__MarketFX__](/transactional-fx__marketfx-overview) allows the Platform to payout foreign currency proceeds quickly and at the best possible rate.



1. A Merchant based in France has been selling on a Marketplace platform based in the United States.
2. The Marketplace platform has been accumulating sales proceeds in USD on behalf of the Merchant until the next scheduled monthly payment.
3. The Marketplace platform aggregates the USD amount payable to the Merchant and prepares it’s run of payouts to all Merchants, including those with an account in a currency other than USD.
4. The Marketplace system sends transfer requests to the Airwallex API with a source currency of USD and a transfer currency of EUR.
5. The Airwallex API sends a response to the Marketplace system with the MarketFX rate and the amount of EUR to be transferred to the Merchant.


Marketplace Platform

Online Travel Agents(OTAs) allow customers to book airline tickets, car rentals, hotel rooms and more through an easy to use online interface. 

OTAs are particularly exposed to FX risk in their commercial transactions and a [__LockFX__](/transactional-fx__lockfx-overview) integration with Airwallex can help to eliminate parts of the risk they face.



1. A hotel in Hong Kong publishes room availability on the OTA platform along with a cost in HKD.
2. A consumer visits the Singapore-based website for the OTA and is browsing hotels to stay in Hong Kong.
3. The OTA system requests a 1 hour validity, single use, SGDHKD quote from the Airwallex API.
4. Airwallex generates a quote and returns it alongside a quote ID in the API response.
5. The OTA system uses this quote to calculate the SGD equivalent for the hotels in HKD and displays on the website - the system will also need to store the quote in the event the consumer makes a purchase.
6. The consumer selects, and pays for the hotel in Hong Kong based on the SGD price they were viewing on the website.
7. The OTA system sends a request to the Airwallex API to convert the SGD to HKD at the quoted rate.


You can make use of the Airwallex Client API to transact foreign exchange using either the MarketFX or LockFX solutions. The following step-by-step instructions can guide you to the simplest way of integrating and getting started transacting with Airwallex in the shortest possible time.

Quickstart Guides

Our MarketFX product provides capability for customers to create conversions from one currency to another at the prevailing market rate via one of our panel of global liquidity providers. MarketFX pricing is provided 24 hours a day, every day of the year to ensure you are always able to transact when you need to.

MarketFX is best suited to customers who are highly transactional and need to be booking many transactions in a short period of time at the best possible rate at the point of conversion. Typical MarketFX customers may be managing FX market risk separately, or be less sensitive to FX market risk. MarketFX is also a simpler integration than LockFX, with no additional need to retrieve and manage quotes. 

![MarketFX Flow](//images.ctfassets.net/c3n7jozh84hr/7MXfbTzGpqIqoDonkZKhIS/c0e91386906f0bb210f30f16077ee620/marketfx.svg)

### MarketFX Transaction Flow

The MarketFX transaction flow can be broken down into its component parts - not all customers will need or want to retrieve an indicative price before placing a conversion request, or transfer request with underlying conversion.

For those that do, you will be able to call the indicative price endpoint via the API.

Following retrieval of the indicative price, you can choose to book a conversion request. Depending on market conditions, and the amount of time you wait between calling for the indicative price and requesting a conversion will determine how much variance there is between the price you get executed at, and the indicative rate initially returned.


![MarketFX Transaction Flow](//images.ctfassets.net/c3n7jozh84hr/4mZPvX7ntUQ3hoP5aghbbT/29f9f4792050362658732d67193c675b/marketfx_1.svg)


### Pricing

Airwallex has integrated with several global and regional banks that provide pricing in both freely traded pairs and in currencies with additional capital controls. Our proprietary MarketFX pricing engine blends prices from across our panel of banks to generate highly available and stable FX prices accessible by clients 24 hours a day, 7 days a week.

Airwallex’s MarketFX pricing algorithm is designed to deliver the best possible price to clients at the time of execution, taking into account a wide variety of factors which may include, but not limited to, current market volatility, available liquidity in the market, the size of the transaction and the selected date you wish to settle the transaction. Any additional agreed margin will be applied on top of the price produced by our MarketFX pricing engine.


MarketFX Overview

Airwallex's LockFX solution is a flexible set of capabilities that customers can integrate with that allows the customer to help eliminate any FX market risk arising from their specific workflows.

The LockFX solution is best suited to businesses that have cross-border transactions, but want to integrate a solution that removes any risk of the FX price moving between the time the business conducts a transaction with one of their own customers and the time at which they convert that revenue to repatriate revenue back to their home domicile.

It is commonly used by customers that have the need to lock in prices for a period of time through a commercial transaction, such as in travel booking processes or marketplace platforms. It is also used in situations where a customer has a workflow with manual intevention, such as 2-step approvals on large transactions.

![LockFX Flow](//images.ctfassets.net/c3n7jozh84hr/2k5GU3grR99b4l95y223aC/4c9cb683792274d805f17b113ceab9b8/lockfx.svg)


### LockFX Transaction Flow

The LockFX transaction flow requires obtaining a price quote prior to requesting a conversion. Following retrieval of a price quote, the quote ID will need to be passed to Airwallex alongside a subsequent conversion request.

The outcome of obtaining a quote will be that the price returned to you on the quote will be guaranteed for the length of the validity period requested, regardless of ongoing market price movements. This allows for certainty in the rate at which you will be executed while users on your platform continue with your existing workflows to book or purchase goods or services.

![LockFX Transaction Flows](//images.ctfassets.net/c3n7jozh84hr/4i2XSAGEW4hm6dEBsEpSkE/06129593ca785bcb2fb8d2197959c1f6/lockfx_1.svg)


### LockFX Pricing

LockFX pricing continues to build on the price produced by the MarketFX pricing engine. Further adjustments are made to the price to take into consideration factors including:



- The validity length of the requested quote;
- Whether the quote requested is valid for multi-use or single-use
- The refund variables assigned against your account (if any)

The integration manager working with you on the integration can guide you through the optimal set-up in LockFX variations to meet your business requirements at the lowest FX cost.




LockFX Overview

Mobile App

This section explains how you will get paid to your account and how Airwallex will charge you for our services.

Payouts - getting paid to your Airwallex balance

Pricing - Airwallex pricing model

Paying and getting paid

The reporting section enables you to obtain in a summarized way the detail of all the transactions that have happened in your account during the last day focusing on different relevant aspects. Specific reports will focus on different aspects of your transactions.


Settlement Report

Reports

The Payments section in the Airwallex Webapp enables you to have access to all the aspects and control your payment acceptance business. The following four sections enable you to manage the different aspects of your business:

- Payments, this section enables you to see the payments you have performed, its status and when required you can drill down to obtain further details about a specific instance.

- Risk, this section enables you to control the Airwallex Risk Engine, the 3D Secure configuration and when you use manual review to complete the actions you are required to.

- Merchant Configuration, this section provides you an overview of the parameters that you can configure for your acceptance platform. Those can only be changed by our support team.


Payments

Risk

Configuration

Webapp  

In this section you will find additional functionalities that will help you to improve your conversion and increase the value that Airwallex Payments brings to you.


Fraud Management

Additional Functionalities

This section provides you an overview of the most common use cases and scenarios that you will need to use when integrating your online commerce with Airwallex

One-off purchase 

One-off purchase with 3D Secure

Recurring transaction

Refunds

Cancellations

Payments Use Cases

Airwallex Platform

Airwallex's own Fraud engine enables you to stop fraud before it occurs and it is fully integrated with the Airwallex Payment Acceptance platform. It leverages our own models in combination with external data sources to discern rouge transactions from legitimate ones.
As a Merchant, you are able to [customize your risk appetite, decide when 3D Secure should be leveraged, or a transaction should be rejected.](https://preview.airwallex.com/docs) Would you prefer to manually review some transactions, we also provide you this possibility.

3D Secure and 3D Secure 2.0

Every Merchant has specific needs and they need to be taken into account. For this purpose the following parameters can be configured when you use the Airwallex Payment Acceptance solution.

May you wish to change any of these contract us


About your Merchant account

About the Payment methods your provide

About how will you get paid

The summary view has double functions for Merchants as you. It enables you to assess at a quick glance how many transactions you have processed, how many of those have been successful and how much revenue you have converted as well as your business conversion metric in regards to payments.

![payment summary - daily data](//images.ctfassets.net/c3n7jozh84hr/1mcdC5j29gD6EG5b2w907E/a3cd29441022870e15f4697d2ee4089d/payment_summary_-_daily_data.png)

Furthermore it enables you to assess if there is any up and down in the revenue you are obtaining over the last day or week either on an amount basis or transactions basis. This can help you to prevent fraud (in case you see spikes at times not common for you), manage your cash-flow (so you can assess if there are more or less purchases coming) and ultimately to get a quick overview of how your business is doing.

![payment summary - heatmap](//images.ctfassets.net/c3n7jozh84hr/5ToN1n6a9p4gu0G4inU11q/3f798b76807c37d2c44551b2b5b571fc/payment_summary_-_heatmap.png)


Payment list

Payment detailed view

At Airwallex we have challenged ourselves to create a transaction model that suits your needs and focuses on what you, our Merchant, cares about.

The main concepts:

 - A __Payment Intent__ represents the aim of your Customer to complete its checkout (and of course pay for your services). In it, you find represented Payment transactions, Refunds and if things go bad also Chargebacks.

 - A __Payment Attempt__ represents an actual trial to perform a financial transaction. It can be a payment transaction, it can be a refund or even a chargeback. When the customer performs several payment trials before completing the purchase you will have one Payment Attempt for each of the attempts, this way you know what happened and can optimize your checkout. The Payment Attempt tracks each and every individual stage through which the transaction goes.

 - A __Financial Transaction__ represents actual and real money. For each Payment Attempt that reaches completion, our platform will generate one or several Financial Transactions. They represent not only the principal amount of your transaction but also the fees associated with it (including gateway fees, interchange fees, markup, etc.), you will have once financial transaction for each of the financial components that are part of a Payment Attempt. Ultimately, only financial transactions will make it to your Airwallex Balance in form or real money.

 - Since there will be many Financial Transactions, a __Batch__ groups all the financial transactions that are paid to you (or you have to pay to Airwallex). A Batch will be adjusted for your eventual rolling reserve and will appear as one line in your Airwallex Balance.

![Illustration - several batches with several different currencies](//images.ctfassets.net/c3n7jozh84hr/3UC3XsIxlDwHZMEQoIbQRw/d62bfea16614c1419a5729d6fe4376eb/PA_-_illustration-several_batches_with_several_different_currencies_and_that_those_go_to_different_multi_currency_wallets.png)


When a Customer wishes to return the goods or services you have provided you can use the refund operation to provide the funds back. It is important that you perform this operation in a timely manner to avoid Disputes raised by the Customers with their banks.

These are the steps you need to follow:

1. Use the Airwallex API or WebApp to create a refund against a specific Payment Intent (or Payment Attempt if you require so). You can perform a full or partial refund; if you make a partial refund several refunds can occur until the principal is fulfilled.

2. You will be immediately informed that the refund request has been received and is being processed.

3. You will be notified when the refund has succeeded through our asynchronous notifications.


The Settlement Report contains each and everyone of the financial transactions derived from your payment intents. One payment intent may have generated several financial transactions. The report is available for you either in an __.xslx__ format (readable with Microsoft Excel or equivalent) or in a zip compressed file containing several CSV files (more suitable for automation purposes).

The Settlement report is composed by two sections that together provide you full visibility and transparency:

 - Settlement provides you the detail of all the payments, refunds, disputes and the aggregate view of the fees that are not netted from a specific payment.

 - Fees provides you the detail of all the fees that are bound to a transaction but are not netted from it (i.e. gateway fee, refund fees, fraud fees, etc.). Ultimately, the Fee section total is provided as one single line in the Settlement section flagged accordingly.
