Accept PayTo payments

This guide describes how to offer PayTo as a payment method on your checkout page using Native API integration.

You can accept PayTo payments in three simple steps:

Create and verify a Payment Consent
Confirm your Payment Intent with a verified Payment Consent
Query Payment Consent status

Create a Payment Consent using the Create a Payment Consent API API

Example request:

JSON
1{
2    "request_id": "1095ab57-ef64-4120-9a84-8a451172184f",
3    "customer_id": "cus_sgstpsxv8h02sf0bof8",
4    "merchant_trigger_reason": "scheduled",
5    "terms_of_use": {
6            "payment_amount_type": "VARIABLE",
7            "payment_schedule": {
8                "period": 1,
9                "period_unit": "WEEK"
10            },
11            "billing_cycle_charge_day": 3,
12            "max_payment_amount": 400,
13            "start_date": "2024-10-20",
14            "end_date": "2025-10-20",
15    },
16    "next_triggered_by": "merchant"
17}

Example response:

JSON
1{
2    "id": "cst_sgstp25tzh02sf1sqw1",
3    "request_id": "1095ab57-ef64-4120-9a84-8a451172184f",
4    "customer_id": "cus_sgstpsxv8h02sf0bof8",
5    "next_triggered_by": "merchant",
6    "merchant_trigger_reason": "scheduled",
7    "status": "REQUIRES_PAYMENT_METHOD",
8    "created_at": "2024-09-19T09:24:11+0000",
9    "updated_at": "2024-09-19T09:24:11+0000",
10    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MjY3Mzc4NTEsImV4cCI6MTcyNjc0MTQ1MSwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiODNlNDYwZDYtYmJkMC00MmU3LTkzZDQtYTllOWVmMDIwNWZmIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0cDI1dHpoMDJzZjFzcXcxIn0.oFX2UMxZBDkkg-AvLOLVoLz2NrmTm7UWhalRIprlG2g",
11    "terms_of_use": {
12        "version": "1.0",
13        "accepted_at": "2024-09-19T09:24:11+0000",
14        "payment_amount_type": "VARIABLE",
15        "max_payment_amount": 400,
16        "payment_schedule": {
17            "period": 1,
18            "period_unit": "WEEK"
19        },
20        "billing_cycle_charge_day": 3,
21        "start_date": "2024-10-20"
22    },
23    "purpose": "recurring"
24}

Ask your customer to authorize the payment agreement via verify Payment Consent API

Example request:

JSON
1{
2    "request_id": "{{$guid}}",
3    "payment_method": {
4        "type": "payto",
5        "payto": {
6            "pay_id": {
7                "owner_email": "[email protected]"
8            }
9        }
10    },
11    "descriptor": "Airwallex",
12    "return_url": "https://www.airwallex.com"
13}

Example response:

JSON
1{
2    "id": "cst_sgstp25tzh02sf1sqw1",
3    "request_id": "bd5fdd47-4dd4-4371-ac85-3302c4f01900",
4    "customer_id": "cus_sgstpsxv8h02sf0bof8",
5    "payment_method": {
6        "type": "payto",
7        "id": "mtd_sgstp25tzh02sf2k5rv",
8        "payto": {
9            "pay_id": {
10                "owner_email": "[email protected]"
11            }
12        }
13    },
14    "next_triggered_by": "merchant",
15    "merchant_trigger_reason": "scheduled",
16    "status": "REQUIRES_CUSTOMER_ACTION",
17    "created_at": "2024-09-19T09:24:11+0000",
18    "updated_at": "2024-09-19T09:24:13+0000",
19    "terms_of_use": {
20        "type": "payto",
21        "version": "1.0",
22        "accepted_at": "2024-09-19T09:24:11+0000",
23        "payment_amount_type": "VARIABLE",
24        "max_payment_amount": 400,
25        "payment_schedule": {
26            "period": 1,
27            "period_unit": "WEEK"
28        },
29        "billing_cycle_charge_day": 3,
30        "start_date": "2024-10-20"
31    },
32    "purpose": "recurring"
33}

Create a Payment Intent using the Create a Payment Intent API API.

Example request:

JSON
1{
2 "request_id": "ac39d2cf-940c-4517-bac0-3601bf533a08",
3    "amount": "100",
4    "email": "[email protected]",
5    "phone": "+8617601215488",
6    "currency": "AUD",
7    "merchant_order_id":"f9bd2bb0-17ad-40e8-acef-da236490dc7c",
8    "order": {
9     "type": "v_goods",
10        "products": [
11            {
12                "code": "3414314111",
13                "name": "IPHONE7",
14                "quantity": 5,
15                "sku": "piece",
16                "type": "physical",
17                "unit_price": 100.01,
18                "url": "test_url",
19                "desc": "test desc"
20            }
21        ],
22     "shipping": {
23      "first_name":"violet",
24      "last_name":"client",
25       "shipping_method": "sameday",
26       "address": {
27         "country_code": "JP",
28         "state": "Shanghai",
29         "city": "Shanghai",
30         "street": "Pudong District",
31         "postcode": "291201"
32       }
33     }
34    },
35    "return_url": "https://www.airwallex.com/",
36    "descriptor":"airwallex"
37}

Example response:

JSON
1{
2    "id": "int_sgstpsxv8h02smzg314",
3    "request_id": "ac39d2cf-940c-4517-bac0-3601bf533a08",
4    "amount": 100,
5    "currency": "AUD",
6    "merchant_order_id": "f9bd2bb0-17ad-40e8-acef-da236490dc7c",
7    "order": {
8        "type": "v_goods",
9        "products": [
10            {
11                "type": "physical",
12                "code": "3414314111",
13                "name": "IPHONE7",
14                "sku": "piece",
15                "quantity": 5,
16                "unit_price": 100.01,
17                "desc": "test desc",
18                "url": "test_url"
19            }
20        ],
21        "shipping": {
22            "first_name": "violet",
23            "last_name": "client",
24            "shipping_method": "sameday",
25            "address": {
26                "country_code": "JP",
27                "state": "Shanghai",
28                "city": "Shanghai",
29                "street": "Pudong District",
30                "postcode": "291201"
31            }
32        }
33    },
34    "descriptor": "airwallex",
35    "status": "REQUIRES_PAYMENT_METHOD",
36    "captured_amount": 0,
37    "created_at": "2024-09-19T09:32:11+0000",
38    "updated_at": "2024-09-19T09:32:11+0000",
39    "available_payment_method_types": [
40        "payto",
41        "becs_direct_debit"
42    ],
43    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MjY3MzgzMzEsImV4cCI6MTcyNjc0MTkzMSwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiODNlNDYwZDYtYmJkMC00MmU3LTkzZDQtYTllOWVmMDIwNWZmIiwiaW50ZW50X2lkIjoiaW50X3Nnc3Rwc3h2OGgwMnNtemczMTQiLCJidXNpbmVzc19uYW1lIjoiQ3VtbWVyYXRhIGFuZCBTb25zIn0.RZFer6JFvEljew4dPDtPIGE8SFLrOBnKf5aMJG05vyI",
44    "base_amount": 100,
45    "base_currency": "AUD",
46    "return_url": "https://www.airwallex.com/"
47}

To collect with PayTo, Confirm your Payment Intent API with a verified Payment Consent

Example request:

JSON
1{
2  "request_id": "958e51a6-685e-4c8c-a4f7-e98fca26fc5e,
3  "payment_consent_id": "cst_sgstp25tzh02smzbczv",
4  "payment_method": {
5    "type": "payto",
6    "payto": {
7        "pay_id": {
8            "owner_email": "[email protected]"
9        }
10    }
11  }
12}

Example response:

JSON
1{
2    "latest_payment_attempt": {
3        "id": "att_sgstp25tzh02sn03fsw_mzg314",
4        "amount": 100,
5        "currency": "AUD",
6        "payment_method": {
7            "customer_id": "cus_sgstpsxv8h02smz6v8m",
8            "type": "payto",
9            "payto": {
10                "pay_id": {
11                    "owner_email": "[email protected]"
12                }
13            }
14        },
15        "merchant_order_id": "f9bd2bb0-17ad-40e8-acef-da236490dc7c",
16        "payment_intent_id": "int_sgstpsxv8h02smzg314",
17        "payment_consent_id": "cst_sgstp25tzh02smzbczv",
18        "status": "AUTHENTICATION_REDIRECTED",
19        "captured_amount": 0,
20        "refunded_amount": 0,
21        "created_at": "2024-09-19T09:32:12+0000",
22        "updated_at": "2024-09-19T09:32:12+0000",
23        "settle_via": "airwallex",
24        ...
25    },
26    "id": "int_sgstpsxv8h02smzg314",
27    "request_id": "958e51a6-685e-4c8c-a4f7-e98fca26fc5e",
28    "amount": 100,
29    "currency": "AUD",
30    "merchant_order_id": "f9bd2bb0-17ad-40e8-acef-da236490dc7c",
31    "payment_consent_id": "cst_sgstp25tzh02smzbczv",
32    "descriptor": "airwallex",
33    "status": "REQUIRES_CUSTOMER_ACTION",
34    "captured_amount": 0,
35    "created_at": "2024-09-19T09:32:11+0000",
36    "updated_at": "2024-09-19T09:32:12+0000",
37    "base_amount": 100,
38    "base_currency": "AUD",
39    "return_url": "https://www.airwallex.com/"
40}

Customers may authorize, pause, or cancel a payment agreement at any time. Airwallex will notify you of any change to the consent status via webhook. Please refer to the webhook documentation to set up your webhook accordingly.

Event	Webhook
Customer authorizes the payment agreement	`payment_consent.verified`
Customer declines or does not authorize the payment agreement before expiry	`payment_consent.verification_failed`
Customer pauses an active agreement	`payment_consent.paused`
Customer cancels an active agreement	`payment_consent.disabled`

Sample webhook

JSON
1{
2      "data": {
3        "object": {
4          "created_at": "2024-09-26T07:08:24+0000",
5          "customer_id": "cus_sgstwqw2kh0aeil11lh",
6          "id": "cst_sgstwqw2kh0aeilaa5r",
7          "merchant_trigger_reason": "scheduled",
8          "next_triggered_by": "merchant",
9          "payment_method": {
10            "type": "payto",
11            "id": "mtd_sgstwqw2kh0aeilf6ux",
12            "payto": {
13              "pay_id": {
14                "owner_email": "[email protected]"
15              }
16            }
17          },
18          "terms_of_use": {
19            "type": "payto",
20            "version": "1.0",
21            "accepted_at": "2024-09-19T09:24:11+0000",
22            "payment_amount_type": "VARIABLE",
23            "max_payment_amount": 400,
24            "payment_schedule": {
25                "period": 1,
26                "period_unit": "WEEK"
27            },
28            "billing_cycle_charge_day": 3,
29            "start_date": "2024-10-20"
30          },
31          "purpose": "recurring",
32          "request_id": "6ed1696d-0858-44ac-a6e9-73e74d041abc",
33          "status": "PAUSED",
34          "updated_at": "2024-09-26T07:08:26+0000"
35        }
36      },
37      "id": "evt_hkdms2c8lgqmwwrlb7b_wqc7nz",
38      "name": "payment_consent.paused",
39      "version": "2019-09-09",
40      "account_id": "acct_k6bE69wNMqWQm6K5Ewdn4g",
41      "created_at": "2024-09-26T07:08:24+0000"
42}

Demo scenarios

Scenarios	Variables
Successfully verify a payment consent	• Set `fixed_payment_amount` or `max_payment_amount` != `400` • Wait for ~5s for the consent to move to the `VERIFIED` state
Failed to verify a payment consent	• Set `fixed_payment_amount` or `max_payment_amount` = `400` • Wait for ~5s for the consent to move to the `DISABLED` state
Successfully initiate a payment	After successfully verifying the consent: • Create a `payment intent` with an amount != `400` • Wait for ~5s for the intent to move to the `SUCCEEDED` state
Failed to initiate a payment	After successfully verifying the consent: • Create a `payment intent` with an amount of `400` • Wait for ~5s for the intent to move to the `FAILED` state
Successfully refund	Once the payment has `SUCCEEDED`, you can create a partial or full refund: • The refund amount must not exceed the original payment amount. • Wait for ~5s for the intent to move to `PARTIALLY REFUNDED` or `FULLY REFUNDED` state
Failed to refund	• Trigger a refund with the refund amount of `4` • Wait for ~5s for the intent to move to `REFUND_FAILED` state

Was this page helpful?

Accept PayTo payments

Step 2. Confirm Payment Intent with a verified Payment Consent

Step 3. Query your Payment Consent status

Demo scenarios