Introduction

Welcome to the SWAPAY API!

The Sandbox SWAPAY API endpoint is https://staging-api.swa-pay.com.
The Production SWAPAY API endpoint is https://api.swa-pay.com.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://staging-api.swa-pay.com" \
  -H "Authorization: meowmeowmeow"

SWAPAY uses API keys to allow access to the API. You can register a new SWAPAY API key at our merchant console.

SWAPAY expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: meowmeowmeow

You must replace meowmeowmeow with your personal API key.

Store information

curl --location --request GET '{{server}}/api/v1/store/detail' \
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3NjA1ODk5MTJ9.oDn9osvEp9jPoz05cQbXoTWV5HsnixLUTlDmk37dkew'
The above command returns JSON structured like this:
{
    "id": "d228a8e2-b6eb-4c1c-8fa7-ea2e53cf2655",
    "store_name": "storeC",
    "office_name": null,
    "representative": null,
    "postal_code": null,
    "province": null,
    "address": null,
    "address2": null,
    "phone": null,
    "token_store": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3NTUwODAwODl9.N15bEeIu4uU-QmrIgIWYY7MTrO-1WoeKjyEpcehiAWQ",
    "logos": null,
    "status": "active",
    "create_date": "2025-08-13T10:14:49.090+00:00",
    "update_date": "2025-10-20T03:02:46.796+00:00",
    "merchant": null,
    "operation_agency": null,
    "owner": {
        "id": "3e7a4538-8a84-4963-9586-6b0b8dd6262b",
        "first_name": null,
        "last_name": null,
        "email": "agency@nft-swapay.com",
        "phone": null,
        "avatar": null,
        "confirmed": null,
        "role": "OPERATION_AGENCY",
        "status": "ACTIVE",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": "agency@nft-swapay.com",
        "display_gateway": "GMO_GATEWAY",
        "address": null,
        "invoice_business_registration_number": null,
        "company_name": null,
        "representative_name": null,
        "account_number": null,
        "user_id": null 
        },
    "contract": {
        "id": "00ac55ca-748c-46e8-bf6c-ac825d7b682f",
        "status": "ACTIVE",
        "corporate_number": "1",
        "company_name": "1",
        "company_name_phonetic": "1",
        "post_code": "1",
        "registered_address": "1",
        "phone_number": "1",
        "fax": "1",
        "representative_name": "1",
        "name_of_representative_furigana": "1",
        "date_of_birth_of_representative": "Fri Dec 22 2023 00:00:00 GMT+0700 (Indochina Time)",
        "representative_address_postal_code": "1",
        "representative_address": "1",
        "online_shop_name": "1",
        "online_shop_url": "1",
        "product_service_details": "1",
        "average_spend_per_customer": "1",
        "handling_product_minimum_unit_price": "1",
        "products_handled_maximum_unit_price": "1"
        },
    "api_key": null,
    "publishable_key": null,
    "alpha_id": null,
    "alpha_pass": null,
    "amount": 0.0,
    "flag_amount": false,
    "trading_type": "REGULAR_PAYMENT",
    "payment_methods": [
        "CREDIT_CARD"
    ],
    "credit_card_types": [
        "VISA_CARD",
        "MASTER_CARD",
        "JCB_CARD",
        "AMEX_CARD",
        "DINERS_CARD"
    ],
    "site_id": null,
    "site_pass": null,
    "shop_id": null,
    "shop_pass": null,
    "public_key": null,
    "public_key_hash": null,
    "gateway_type": "FIN_CODE_GATEWAY",
    "merchant_ccid": null,
    "merchant_secret_key": null,
    "token_api_key": null,
    "td_flag": null,
    "tenant": null,
    "min_amount": 1.0,
    "max_amount": 9999999.0,
    "limit_amount": false,
    "shop_name": null,
    "shop_name_kana": null,
    "parent_shop_id": null,
    "parent_shop_name": null,
    "shop_type": null,
    "back_account_list": null,
    "transfer_destination": "DIRECT_MERCHANT",
    "methods": [
        "ONE_TIME"
    ],
    "receipt_enabled": true,
    "send_payment_success_email": true,
    "keywords": null,
    "pre_authentication": true
}
Abnormal

{
  "code": "E0401",
  "message": "Invalid authorization code",
  "errors": null
}

The API returns the current store’s configuration and profile (e.g., name, status, payment gateway, enabled payment methods, amount limits, etc.).

HTTP Request

GET /v1/store/detail

Production environment https://api.swa-pay.com/api/v1/store/detail

Staging environment https://staging-api.swa-pay.com/api/v1/store/detail

Store Response Fields

Field	Type	Description
id	`UUID`	Store ID on SWAPay
store_name	`String`	Store name
token_store	`String`	Store-scoped token (sensitive)
status	`String`	Store status (`request_active`,`active`, `request_delete`, `deleted`)
create_date	`DateTime`	Store creation time
update_date	`DateTime`	Last updated time
owner	`Object`	Owner info (see Owner Fields)
contract	`Object`	Store’s signed contract info (see Contract Fields)
amount	`Number`	Verification amount threshold (if used)
flag_amount	`Boolean`	Whether `amount` rule is enabled
trading_type	`String`	Operation method (`REGULAR_PAYMENT`, `ESCROW_PAYMENT`, `TEMPORARY_SALES_PAYMENT`)
payment_methods	`Array<String>`	Enabled payment methods (e.g., `CREDIT_CARD`, `PAYPAY`, `LINEPAY`, `APPLEPAY`, `GOOGLE_PAY`)
credit_card_types	`Array<String>`	Accepted card brands (`VISA_CARD`, `MASTER_CARD`, `JCB_CARD`, `AMEX_CARD`, `DINERS_CARD`)
gateway_type	`String`	Configured gateway (e.g., `FIN_CODE_GATEWAY`, `ALPHA_NOTE_GATEWAY`, `GMO_GATEWAY`)
min_amount	`Number`	Minimum allowed payment amount
max_amount	`Number`	Maximum allowed payment amount
limit_amount	`Boolean`	Whether min/max amount limits are enforced
transfer_destination	`String`	Settlement destination policy (e.g., `DIRECT_MERCHANT`)
methods	`Array<String>`	Allowed billing types (`ONE_TIME`, `INSTALLMENT`, `REVOLVING`, `SUBSCRIPTION`)
receipt_enabled	`Boolean`	Whether receipt issuance is enabled
send_payment_success_email	`Boolean`	Whether to send payment-success emails
pre_authentication	`Boolean`	Require 3DS2 pre-authentication at card registration (¥10 test charge → auto-refund on success)

Owner Fields

Field	Type	Description
id	`UUID`	Owner user ID
email	`String`	Owner email
role	`String`	Owner role (e.g., `OPERATION_AGENCY`, `MERCHANT`)
status	`String`	Owner account status (e.g., `ACTIVE`)
display_name	`String`	Owner display name
display_gateway	`String`	Preferred display gateway (e.g., `GMO_GATEWAY`)

Contract Fields

Field	Type	Description
id	`UUID`	Contract ID
status	`String`	Contract status (e.g., `ACTIVE`)
corporate_number	`String`	Corporate number
company_name	`String`	Company name
company_name_phonetic	`String`	Company name (phonetic)
post_code	`String`	Company postal code
registered_address	`String`	Registered corporate address
phone_number	`String`	Company phone number
fax	`String`	Company fax
representative_name	`String`	Legal representative name
name_of_representative_furigana	`String`	Representative name (furigana)
date_of_birth_of_representative	`String`	Representative’s DOB (as provided)
representative_address_postal_code	`String`	Representative postal code
representative_address	`String`	Representative address
online_shop_name	`String`	Online shop name
online_shop_url	`String`	Online shop URL
product_service_details	`String`	Description of products/services
average_spend_per_customer	`String`	Average spend per customer
handling_product_minimum_unit_price	`String`	Minimum unit price handled
products_handled_maximum_unit_price	`String`	Maximum unit price handled

Orders

Create a new Order

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/order' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pay_amount": 1000.0,
    "currency": "JPY",
    "customer_id": "1000",
    "customer_order_id": "1001",
    "description": "NFT",
    "success_url": "https://swapay.co.jp/",
    "callback_url": "https://swapay.co.jp/",
    "cancel_url": "https://swapay.co.jp/",
    "selected_payment_type": "INSTALLMENT",
    "selected_installment_term": 6
}'

{
    "id": "8405b5f8-0244-4bd5-97cb-748ddeac6b13",
    "pay_amount": 1000.0,
    "currency": "JPY",
    "customer_id": "1000",
    "customer_order_id": "1001",
    "description": null,
    "consumer_id": null,
    "store": {
        "id": "0d630192-d7f3-4c05-8540-19d91f2aaa4b",
        "store_name": "NFT SWAP STORE 3",
        "office_name": "NFT SWAP STORE"
    },
    "merchant": {
        "id": "af40eee0-81ad-4e29-a8ea-87603b3f8282",
        "display_name": "Kenji Umemura"
    },
    "success_url": "https://swapay.co.jp/",
    "cancel_url": "https://swapay.co.jp/",
    "callback_url": "https://swapay.co.jp/",
    "status": "WAITING_FOR_PAYMENT",
    "user_create": null,
    "create_date": "2022-07-25T05:34:31.631+00:00",
    "user_update": null,
    "update_date": null,
    "payment_url": "https://staging-api.swa-pay.com/gateway/payment/8405b5f8-0244-4bd5-97cb-748ddeac6b13",
    "pay_method": null,
    "pay_times": null,
    "selected_payment_type": "INSTALLMENT",
    "selected_installment_term": 6
}

{
    "code": "101",
    "message": "Missing amount",
    "errors": null
}

This endpoint will help you to start a transaction

HTTP Request

POST /v1/order

Production environment https://api.swa-pay.com/api/v1/order

Staging environment https://staging-api.swa-pay.com/api/v1/order

JSON Object Payload Parameters

Parameter	Type	Required	Description
pay_amount	Double	true	Amount of the transaction
currency	String	false	The currency used for payment. Default is JPY
description	String	false	Description of the transaction
customer_id	String	false	The customer id on merchant system
customer_order_id	String	false	The order id on merchant systems
success_url	String	false	Redirect to `success_url` after successful payment
callback_url	String	false	JSON-formatted `POST` notification message will be sent to `callback_url` when order status is changed. If the callback is empty, we can send information to merchant's email.
cancel_url	String	false	Redirect to `cancel_url` when buyer cancels the order
user_id	String	false	The customer ID on SWAPay system (Returned in the user registration api)
consumer_email	String	false	Email of customer
consumer_phone	String	false	Phone of consumer
selected_payment_type	String or null	false	Enum: "ONE_TIME" "INSTALLMENT" "REVOLVING" ONE_TIME: One-time payment (default), INSTALLMENT: Installment payment, REVOLVING: Revolving payment
selected_installment_term	String or null	false	Enum: "3" "5" "6" "10" "12" "15" "18" "20" "24" (For installments) Number of payments

System will send confirmation message after payment with contact information registered with user_id.
If there is no user_id, you can send consumer_email or consumer_phone. So that the system can send a confirmation message after payment

Order Response Fields

Field	Type	Description
id	UUID	Payment request ID on NFT SWAP System
pay_amount	Double	Total amount to be paid
currency	String	The currency used for payment. Default is JPY
customer_id	String	The customer id on merchant system
user_id	String	false
customer_order_id	String	The order id on merchant systems
description	String	Description of the transaction
store
merchant
success_url	String	Redirect to `success_url` after successful payment
cancel_url	String	Redirect to `cancel_url` when buyer cancels the order
callback_url	String	JSON-formatted `POST` notification message will be sent to `callback_url` when order status is changed. If the callback is empty, we can send information to merchant's email.
status	String	Status of Payment request
pay_method	String
payment_url	String	The customer will process the payment at this site.
pay_times	Number
update_date	DateTime
create_date	DateTime
selected_payment_type	String or null	Enum: "ONE_TIME" "INSTALLMENT" "REVOLVING"
selected_installment_term	String or null	Enum: "3" "5" "6" "10" "12" "15" "18" "20" "24" (For installments) Number of payments

Update a order

curl --location --request PUT 'https://staging-api.swa-pay.com/api/v1/store/orders/c2b5512c-7ef2-4590-bfb7-3eb2874b2187' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pay_amount": 1000
}'

{
    "id": "ed2b2b6c-f88a-468a-a94e-7585925e4e83",
    "pay_amount": 1000.0,
    "pay_next_month": 1000.0,
    "currency": "JPY",
    "customer_id": "1000",
    "customer_order_id": "1001",
    "description": "NFT",
    "consumer_id": null,
    "store": {
        "id": "eba99e3f-84bc-4b92-a215-e0289a5fdcb2",
        "store_name": "NFT SWAP STORE",
        "office_name": "NFT SWAP STORE"
    },
    "merchant": {
        "id": "af40eee0-81ad-4e29-a8ea-87603b3f8282",
        "display_name": "merchant@nft-swapay.com"
    },
    "success_url": "https://swapay.co.jp/",
    "cancel_url": "https://swapay.co.jp/",
    "callback_url": "https://3c80-2405-4802-9119-ab90-e86d-6d5a-d791-666c.ap.ngrok.io/gateway/receiving",
    "status": "WAITING_FOR_PAYMENT",
    "user_create": null,
    "create_date": "2022-08-13T02:14:41.314+00:00",
    "monthly_payment_date": null,
    "user_update": null,
    "update_date": "2022-08-13T02:14:41.314+00:00",
    "payment_url": "https://149c-123-20-166-241.ap.ngrok.io/gateway/payment/ed2b2b6c-f88a-468a-a94e-7585925e4e83",
    "pay_method": null,
    "pay_times": null,
    "consumer_email": null,
    "user_id": null,
    "subscribe": null,
    "selected_payment_type": "ONE_TIME",
    "selected_installment_term": null
}

This endpoint will help you to change the payment details of transactions.

HTTP Request

PUT /v1/store/orders/{id}

Production environment https://api.swa-pay.com/api/v1/store/orders/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/store/orders/{id}

JSON Object Payload Parameters

Parameter	Type	Required	Description
pay_amount	Double	false	Recurring payment amount
description	String	false	Description of the transaction
date_payment	DateTime	false

Get All Orders

curl --location --request GET 'https://staging-api.swa-pay.com/api/v1/store/orders' \
--header 'Authorization: meowmeowmeow'

[
    {
        "id": "8405b5f8-0244-4bd5-97cb-748ddeac6b13",
        "pay_amount": 1000.0,
        "currency": "JPY",
        "customer_id": "1000",
        "customer_order_id": "1001",
        "description": null,
        "consumer_id": null,
        "store": {
            "id": "0d630192-d7f3-4c05-8540-19d91f2aaa4b",
            "store_name": "NFT SWAP STORE 3",
            "office_name": "NFT SWAP STORE"
        },
        "merchant": {
            "id": "af40eee0-81ad-4e29-a8ea-87603b3f8282",
            "display_name": "Kenji Umemura"
        },
        "success_url": "https://swapay.co.jp/",
        "cancel_url": "https://swapay.co.jp/",
        "callback_url": "https://swapay.co.jp/",
        "status": "WAITING_FOR_PAYMENT",
        "user_create": null,
        "create_date": "2022-07-25T05:34:31.631+00:00",
        "user_update": null,
        "update_date": null,
        "payment_url": "https://staging-api.swa-pay.com/gateway/payment/8405b5f8-0244-4bd5-97cb-748ddeac6b13",
        "pay_method": null,
        "pay_times": null
    }
]

This endpoint retrieves all Orders.

HTTP Request

GET /v1/store/orders

Production environment https://api.swa-pay.com/api/v1/store/orders

Staging environment https://staging-api.swa-pay.com/api/v1/store/orders

Query Parameters

Parameter	Default	Description
page	1
per_page	30

Get status a Order

curl --location --request GET "https://staging-api.swa-pay.com/api/v1/store/orders/5c73f272-ebc8-4428-8a84-36e3d0230910" \
--header 'Authorization: meowmeowmeow'

{
    "id": "5c73f272-ebc8-4428-8a84-36e3d0230910",
    "pay_amount": 1000.0,
    "currency": null,
    "customer_id": null,
    "customer_order_id": null,
    "description": "Sample order",
    "consumer_id": null,
    "success_url": null,
    "cancel_url": null,
    "callback_url": null,
    "status": "WAITING_FOR_PAYMENT",
    "user_create": "af40eee0-81ad-4e29-a8ea-87603b3f8282",
    "create_date": "2022-07-08T07:43:02.612+00:00",
    "user_update": "af40eee0-81ad-4e29-a8ea-87603b3f8282",
    "update_date": "2022-07-08T07:43:02.612+00:00",
    "payment_url": "/gateway/payment/764acfd2-18dc-45ca-9596-fcd5ec4ddcc6"
}

This endpoint get a specific order information.

HTTP Request

GET /v1/store/orders/{id}

Production environment https://api.swa-pay.com/api/v1/store/orders/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/store/orders/{id}

URL Parameters

Parameter	Description
id	The ID of the order

Order Status

Status Code	Meaning
TEMPORARY_SAVE	The temporary save status of the order.
WAITING_FOR_PAYMENT	The Waiting for payment status means that we still are waiting for payment.
OTP_CONFIRMING	Waiting for OTP confirming from Email/SMS.
OTP_TIMEOUT	Cannot confirm OTP after 30 minutes.
AUTHENTICATING_3DS	Waiting for 3DS Authentication.
TIMEOUT_3DS	3DS timeout after 30 minutes.
PROCESSING	The transaction is paid and waiting to be confirmed.
COMPLETE	The transaction was successfully.
REFUNDED	The transaction is refunded.
CANCEL	This payment has been canceled while the transaction status was "TEMPORARY_SAVE" or "WAITING_FOR_PAYMENT" and was canceled by the user or merchant.
ERROR	An error occurred during the payment process.

Payment Method of order

Name	Value	Meaning
CREDIT_CARD	0	Credit card payment
CASH	1	Cash payment
PAYPAY	2	Paypay payment
FAMIPAY	3	Famipay payment
LINEPAY	4	Linepay payment
APPLEPAY	5	Applepay payment

Pay Type Method for payment

Name	Value	Meaning
ONE_TIME	ONE_TIME	One Time payment
INSTALLMENT	INSTALLMENT	INSTALLMENT type payment
REVOLVING	REVOLVING	REVOLVING type payment

Callback Response Message

{
  "id": "0125709b-8837-42fa-a11d-d8f57ebc6e0f",
  "pay_amount": 4000,
  "currency": "JPY",
  "customer_id": null,
  "customer_order_id": "20250324_1460",
  "status": "PROCESSING",
  "update_date": 1742803936591,
  "create_date": 1742803923044,
  "pay_method": "0",
  "pay_times": null,
  "actual_payment_date": 1742803936591,
  "confirmed_at": null,
  "authenticating_date": 1742803936591,
  "user_payment": {
    "id": "4f301013-4e7f-4d5c-8254-f1dc8200bd77",
    "first_name": "Hieu",
    "last_name": "ta pham kim",
    "email": "hieutaphamkim89@gmail.com",
    "phone": "0964-11-1111",
    "affiliate_code": null,
    "display_name": "ta pham kim Hieu",
    "address": "Ho Chi Minh"
  }
}

We'll let you know when a transaction changes status via callback_url.

Callback Response Fields

Field	Type	Description
id	UUID	Unique identifier of the payment request
pay_amount	Double	Payment amount
currency	String	Currency code (e.g., "JPY", "USD")
customer_id	String or null	Customer identifier (nullable)
customer_order_id	String	ID of the order from the customer system
status	String	Status of the payment request (e.g., PROCESSING, COMPLETE)
update_date	Timestamp (epoch millis)	Last updated time of the transaction
create_date	Timestamp (epoch millis)	Created time of the transaction
pay_method	String	Payment method code (e.g., "0")
pay_times	Int or null	Number of payment installments (nullable)
actual_payment_date	Timestamp (epoch millis)	Time the payment was actually made
confirmed_at	Timestamp (epoch millis) or null	Time the transaction was confirmed
authenticating_date	Timestamp (epoch millis)	Authentication time of the transaction
user_payment	Object	Info of the user who made the payment (see below)

user_payment object fields

Field	Type	Description
id	UUID	User ID
first_name	String	User's first name
last_name	String	User's last name
email	String	User's email
phone	String	User's phone number
affiliate_code	String or null	Affiliate code if any
display_name	String	Display name of the user
address	String	User's address

Settlement

Make a payment by communicating with the card company.

When making a payment using a token

When paying with a member ID

If you omit tds_type or send a value other than "0", or the store has not enabled Pre-Authentication, the API will require 3DS2.

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MDUzMTU5NDV9.xT3EFN3SC51hORCMEaSDeoA1KEGwGm7cAXdIFQtxr28' \
--header 'Content-Type: application/json' \
--data-raw {
  "id": "644c7d8a-d01d-41c6-a63f-4afd88fe9687",
  "card_id": "9cd378b2-7086-4d69-b245-95b97f84f0da",
  "user_id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4"
}

{
    "id": "644c7d8a-d01d-41c6-a63f-4afd88fe9687",
    "pay_amount": 1200.0,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": "20251019_1531",
    "status": "AUTHENTICATING_3DS",
    "update_date": "2025-10-19T08:33:09.913+00:00",
    "create_date": "2025-10-19T08:33:09.913+00:00",
    "pay_method": "0",
    "pay_times": null,
    "order_id_csv": null,
    "actual_payment_date": null,
    "confirmed_at": null,
    "acs": "2",
    "acs_url": "https://simulator.test.fincode.jp/payment/Tds2StubCallback.idPass?transId=86008da1-5d64-4605-bd1f-3dab3c84f6bf&t=a_Kw9Mm5zRTbeCpgCggcYTLA",
    "redirect_url": "https://staging-api.swa-pay.com/api/v1/fincode/secure/authentication/644c7d8a-d01d-41c6-a63f-4afd88fe9687",
    "user_payment": {
        "id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
        "first_name": "hieu",
        "last_name": "taphamkim",
        "email": "hieutaphamkim89+1750@gmail.com",
        "phone": null,
        "affiliate_code": null,
        "display_name": "taphamkim hieu",
        "address": null
    },
    "state": null
}

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MDUzMTU5NDV9.xT3EFN3SC51hORCMEaSDeoA1KEGwGm7cAXdIFQtxr28' \
--header 'Content-Type: application/json' \
--data-raw {
    "id": "{{order_id}}",
    "card_id": "{{card_id}}",
    "user_id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
    "tds_type": "0"
}

{
    "id": "22be11b0-d075-496d-9bae-615daf730cd1",
    "pay_amount": 1400.0,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": "20251019_1731",
    "status": "COMPLETE",
    "update_date": "2025-10-19T08:16:32.526+00:00",
    "create_date": "2025-10-19T08:12:42.377+00:00",
    "pay_method": "0",
    "pay_times": null,
    "order_id_csv": null,
    "actual_payment_date": "2025-10-19T08:16:32.526+00:00",
    "confirmed_at": null,
    "acs": null,
    "acs_url": null,
    "redirect_url": null,
    "user_payment": {
        "id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
        "first_name": "hieu",
        "last_name": "taphamkim",
        "email": "hieutaphamkim89+1750@gmail.com",
        "phone": null,
        "affiliate_code": null,
        "display_name": "taphamkim hieu",
        "address": null 
        },
    "state": null
}

{
    "code": "E0429",
    "message": "Pre-Authentication is not enabled for this store. Please contact an administrator to enable it.",
    "errors": null
}

{
    "code": "E0430",
    "message": "This card was not 3DS-authenticated at registration.",
    "errors": null
}

HTTP Request

POST /v1/payment

Production environment https://api.swa-pay.com/api/v1/payment

Staging environment https://staging-api.swa-pay.com/api/v1/payment

JSON Object Payload Parameters

Parameter	Required	Description
id	true	Transaction/order ID
card_id	true	Stored card ID on SWAPay
user_id	true	Payer’s user ID
tds_type	false	"0": Do not use 3D Secure authentication. "2": Use 3D Secure 2.0 authentication (default)

When making a payment using a card number - No 3DS

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: meowmeowmeow.' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "8405b5f8-0244-4bd5-97cb-748ddeac6b13",
    "card_no": "4100000000000100",
    "expire": "12/25",
    "security_code": "123",
    "holder_name": "LYBIA SOFT"
}'

{
    "id": "d1702c31-617a-4d51-afca-d135e7034f8a",
    "pay_amount": 1000.0,
    "currency": "JPY",
    "customer_id": "1000",
    "customer_order_id": "1001",
    "status": "COMPLETE",
    "update_date": null,
    "pay_method": null,
    "pay_times": null
}

{
    "code": "M01004014",
    "message": "Order ID is already part of a transaction requesting settlement",
    "errors": [
        {
            "errInfo": "E01050004",
            "errCode": "E01"
        },
        {
            "errInfo": "M01004014",
            "errCode": "M01"
        }
    ]
}

This endpoint will help you to payment for a transaction

HTTP Request

POST /v1/payment

Production environment https://api.swa-pay.com/api/v1/payment

Staging environment https://staging-api.swa-pay.com/api/v1/payment

JSON Object Payload Parameters

Parameter	Required	Description
id	true	ID of the transaction
card_no	true	credit card number
expire	true	Credit card expiration date - MMYY format
security_code	true	security code - The 3- or 4-digit number printed on the card
holder_name	true	Credit card name

Cancel a payment

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment_cancel' \
--header 'Authorization: meowmeowmeow.' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "048874d9-3029-4c0f-a738-93b16c66d948"
}'

{
    "id": "048874d9-3029-4c0f-a738-93b16c66d948",
    "pay_amount": 1000.0,
    "currency": "JPY",
    "customer_id": "1000",
    "customer_order_id": "1001",
    "description": "NFT",
    "consumer_id": null,
    "pay_method": "0",
    "success_url": "https://swapay.co.jp/",
    "cancel_url": "https://swapay.co.jp/",
    "callback_url": "https://149c-123-20-166-241.ap.ngrok.io/gateway/callback",
    "status": "REJECTED",
    "create_date": "2022-08-02T12:57:15.322+00:00",
    "update_date": "2022-08-02T12:57:18.066+00:00",
    "pay_method": null,
    "pay_times": null,
    "consumer_email": null,
    "payment_url": "/gateway/payment/048874d9-3029-4c0f-a738-93b16c66d948"
}

{
    "code": "303",
    "message": "The status of the order does not allow this action",
    "errors": null
}

This endpoint will help you to payment for a transaction

HTTP Request

POST /v1/payment_cancel

Production environment https://api.swa-pay.com/api/v1/payment_cancel

Staging environment https://staging-api.swa-pay.com/api/v1/payment_cancel

JSON Object Payload Parameters

Parameter	Required	Description
id	true	ID of the transaction

Settlement - 3DS-2 (support for the GMO Gateway, the FinCode Gateway and the Alpha note gateway)

3DS-2 card number

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: meowmeowmeow.' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "79ec92ea-e4fe-4b02-ae3d-b1aa962bae66",
    "card_no": "4100 0000 0000 5000",
    "expire": "1229",
    "security_code": "123",
    "holder_name": "LYBIA SOFT"
}'

{
    "pay_amount": 1000.0,
    "currency": "JPY",
    "customer_id": "102",
    "customer_order_id": null,
    "status": "AUTHENTICATING_3DS",
    "update_date": "2025-08-13T07:03:39.080+00:00",
    "create_date": "2025-08-13T07:03:39.080+00:00",
    "pay_method": "0",
    "pay_times": null,
    "order_id_csv": null,
    "actual_payment_date": null,
    "confirmed_at": null,
    "acs": "2",
    "acs_url": "https://simulator.test.fincode.jp/payment/Tds2StubCallback.idPass?transId=63c06889-d237-4bcc-9e7b-dfe4bc05beae&t=a_akfQCPrfR4yazH6cedT1RA",
    "redirect_url": "https://staging-api.swa-pay.com/api/v1/fincode/secure/authentication/79ec92ea-e4fe-4b02-ae3d-b1aa962bae66",
    "user_payment": null,
    "state": null
}

This endpoint will help you to start payment for a transaction

HTTP Request

POST /v1/payment

Production environment https://api.swa-pay.com/api/v1/payment

Staging environment https://staging-api.swa-pay.com/api/v1/payment

JSON Object Payload Parameters

Parameter	Type	Description
`id`	UUID	ID of the transaction.
`pay_amount`	Double	Amount of the transaction.
`currency`	String	The currency used for payment. Default is `JPY`.
`customer_id`	String	The customer ID in the merchant system.
`customer_order_id`	String	The order ID in the merchant system.
`status`	String	Status of the payment request.
`acs`	String	Indicates whether to use 3D Secure authentication. `0`: Do not use 3D Secure authentication (default). `2`: Use 3D Secure 2.0 authentication.
`acs_url`	String	URL of the 3D Secure authentication page returned directly from the payment gateway. Used only when your system implements the entire 3D Secure authentication process.
`redirect_url`	String	3D Secure authentication URL provided by Swapay. This URL is customized to simplify integration and can be used as an alternative to `acs_url` if you prefer Swapay to handle part or all of the 3D Secure authentication flow.
`pay_method`	String	Payment method. `0`: Credit card payment.
`state`	String	Payment result status. `1`: Payment successful. `2`: Payment failed. `3`: 3D Secure authentication required. Only applicable for the Alphanote payment gateway.

Settlement - PAYPAY (support for the GMO Gateway and the FinCode Gateway)

Payment with PayPay method

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: {store_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "1c2705ce-4eed-47eb-a753-0e6b0d6c151a",
    "payment_method": "paypay"
}'

{
    "id": "1c2705ce-4eed-47eb-a753-0e6b0d6c151a",
    "pay_amount": 2600.0,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": "689190",
    "status": "WAITING_FOR_PAYMENT",
    "update_date": "2024-05-27T08:10:47.261+00:00",
    "create_date": "2024-05-27T08:10:47.261+00:00",
    "pay_method": "2",
    "pay_times": null,
    "order_id_csv": null,
    "actual_payment_date": null,
    "confirmed_at": null,
    "acs": null,
    "acs_url": null,
    "redirect_url": "https://staging-api.swa-pay.com/api/v1/gmo/paypay/start/1c2705ce-4eed-47eb-a753-0e6b0d6c151a"
}

This endpoint will help you to start payment for a transaction

HTTP Request

POST /v1/payment

Production environment https://api.swa-pay.com/api/v1/payment

Staging environment https://staging-api.swa-pay.com/api/v1/payment

JSON Object Payload Parameters

Parameter	Required	Description
id	true	ID of the transaction
payment_method	true	value: paypay
customer_id	false	The customer id on merchant system

JSON Object Payload Parameters

Parameter	Type	Description
id	UUID	ID of the transaction
pay_amount	Double	Amount of the transaction
currency	String	The currency used for payment. Default is JPY
customer_id	String	The customer id on merchant system
customer_order_id	String	The order id on merchant systems
status	String	Status of Payment request
redirect_url	String	Redirect URL for payment with PayPay
pay_method	String	2 => (Paypay payment)

Settlement - LinePay (support for the GMO Gateway)

Payment with LinePay method

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/payment' \
--header 'Authorization: {store_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "09e68717-391a-4b01-87cb-0ccd7305eb8e",
    "payment_method": "linepay"
}'

{
    "id": "6cce744b-4122-44e8-992f-2ef6a53e2835",
    "pay_amount": 2600.0,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": "3780402",
    "status": "WAITING_FOR_PAYMENT",
    "update_date": "2024-05-28T03:00:44.037+00:00",
    "create_date": "2024-05-28T03:00:44.037+00:00",
    "pay_method": "4",
    "pay_times": null,
    "order_id_csv": null,
    "actual_payment_date": null,
    "confirmed_at": null,
    "acs": null,
    "acs_url": null,
    "redirect_url": "https://staging-api.swa-pay.com/api/v1/gmo/linepay/start/6cce744b-4122-44e8-992f-2ef6a53e2835"
}

This endpoint will help you to start payment for a transaction

HTTP Request

POST /v1/payment

Production environment https://api.swa-pay.com/api/v1/payment

Staging environment https://staging-api.swa-pay.com/api/v1/payment

JSON Object Payload Parameters

Parameter	Required	Description
id	true	ID of the transaction
payment_method	true	value: paypay
customer_id	false	The customer id on merchant system

JSON Object Payload Parameters

Parameter	Type	Description
id	UUID	ID of the transaction
pay_amount	Double	Amount of the transaction
currency	String	The currency used for payment. Default is JPY
customer_id	String	The customer id on merchant system
customer_order_id	String	The order id on merchant systems
status	String	Status of Payment request
redirect_url	String	Redirect URL for payment with Linepay
pay_method	String	4 => (linepay payment)

Users

User registration

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/customers' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone": "+81973666666",
    "email": "thanhphat@gmail.com",
    "first_name": "Phat",
    "last_name": "Lam"
}'

{
    "id": "9b377f6c-6b83-42ac-866a-5a9a9171ca88",
    "active": false,
    "confirmed": false,
    "username": null,
    "first_name": "Phat",
    "last_name": "Lam",
    "email": "thanhphat@gmail.com",
    "phone": "+81973666666",
    "address": null
}

{
    "code": "E0010",
    "message": "Email is already used",
    "errors": null
}

This endpoint will help you register a user on SWAPAY system.

HTTP Request

POST /v1/customers

Production environment https://api.swa-pay.com/api/v1/customers

Staging environment https://staging-api.swa-pay.com/api/v1/customers

JSON Object Payload Parameters

Parameter	Required	Description
customer_id	false	The customer id on merchant system
first_name	false	The member's first name
last_name	false	The member's last name
email	true	The member's email. If the member uses the phone number. Then no need for email
phone	true	The member's phone . If the member uses the mail. Then no need for phone
country_code	false	The member's country code. Default JP
address	false	The member's address

Error code list

Error Code	Meaning
E0010	Email is already used
E0019	Customer ID is already used

User Response Fields

Field	Type	Description
id	UUID	User ID on SWAPay System
email	String	Email
first_name	String	First name
last_name	String	Last name
phone	String	Phone number
confirmed	Boolean	`true` if the customer's email is confirmed. `false` if the customer's email isn't confirmed
phone_confirmed_at	DateTime	The time when the phone is confirmed.
provider	String	`PHONE` if customer is registered with phone number. `EMAIL` if customer is registered with email address
address	String	Address
avatar	String	The avatar URL
create_date	DateTime	The time when customer is registered

Get User profile

curl --location --request GET 'https://staging-api.swa-pay.com/api/v1/customers/b68904c8-cb4b-4685-a7fb-3ee0cd99f5c2' \
--header 'Authorization: meowmeowmeow'

{
    "id": "b68904c8-cb4b-4685-a7fb-3ee0cd99f5c2",
    "confirmed": false,
    "phone_confirmed_at": null,
    "username": null,
    "first_name": null,
    "last_name": null,
    "display_name": "lybiasoft@gmail.com",
    "phone": null,
    "address": null,
    "avatar": null,
    "email": "lybiasoft@gmail.com",
    "country_code": null,
    "phone_e164": null,
    "provider": "EMAIL",
    "customer_id": null,
    "create_date": "2022-09-10T23:55:55.003+00:00"
}

{
    "code": "E0208",
    "message": "User not found",
    "errors": null
}

This endpoint will help you get a user profile on SWAPAY system.

HTTP Request

POST /v1/customers/{id}

Production environment https://api.swa-pay.com/api/v1/customers/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/customers/{id}

URL Parameters

Parameter	Description
id	The ID of the user

Update User profile

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/customers/9af4f665-9869-4c95-99ca-51d14a32d50f' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone": "+81973666666",
    "email": "thanhphat@gmail.com",
    "first_name": "Phat 1",
    "last_name": "Lam"
}'

{
    "id": "b68904c8-cb4b-4685-a7fb-3ee0cd99f5c2",
    "confirmed": false,
    "phone_confirmed_at": null,
    "username": null,
    "first_name": "Phat 1",
    "last_name": "Lam",
    "display_name": "Phat 1 Lam",
    "phone": "+81973666666",
    "address": null,
    "avatar": null,
    "email": "lybiasoft@gmail.com",
    "country_code": null,
    "phone_e164": null,
    "provider": "EMAIL",
    "customer_id": null,
    "create_date": "2022-09-10T23:55:55.003+00:00"
}

{
    "code": "E0010",
    "message": "Email is already used",
    "errors": null
}

This endpoint will help you update user profile on SWAPAY system.

HTTP Request

POST /v1/customers/{id}

Production environment https://api.swa-pay.com/api/v1/customers/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/customers/{id}

URL Parameters

Parameter	Description
id	The ID of the user

JSON Object Payload Parameters

Parameter	Required	Description
first_name	false	The member's first name
last_name	false	The member's last name
email	true	The member's email
phone	true	The member's phone
address	false	The member's address

Re-send verification message

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/customers/b68904c8-cb4b-4685-a7fb-3ee0cd99f5c2/resend_verification' \
--header 'Authorization: meowmeowmeow'

{
    "id": "b68904c8-cb4b-4685-a7fb-3ee0cd99f5c2",
    "confirmed": false,
    "phone_confirmed_at": null,
    "username": null,
    "first_name": null,
    "last_name": null,
    "display_name": "lybiasoft@gmail.com",
    "phone": null,
    "address": null,
    "avatar": null,
    "email": "lybiasoft@gmail.com",
    "country_code": null,
    "phone_e164": null,
    "provider": "EMAIL",
    "customer_id": null,
    "create_date": "2022-09-10T23:55:55.003+00:00"
}

{
    "code": "E0035",
    "message": "The customer is confirmed",
    "errors": null
}

This endpoint will help you resend the verification message to user.

HTTP Request

POST /v1/customers/{id}/resend_verification

Production environment https://api.swa-pay.com/api/v1/customers/{id}/resend_verification

Staging environment https://staging-api.swa-pay.com/api/v1/customers/{id}/resend_verification

URL Parameters

Parameter	Description
id	The ID of the user

Verify user with phone number

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/verify' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone": "09078115642",
    "country_code": "JP",
    "code": "881495"
}'

{
    "id": "9af4f665-9869-4c95-99ca-51d14a32d50f",
    "active": false,
    "confirmed": false,
    "username": null,
    "first_name": null,
    "last_name": null,
    "email": null,
    "phone": "+819078115642",
    "address": null,
    "phone_confirmed_at": "2022-08-13T09:13:33.745+00:00"
}

This endpoint will help the customers verify their phone number. SWAPay system will send an OTP code via SMS. The customers need check the new SMS and input OTP.

HTTP Request

POST /v1/verify

Production environment https://api.swa-pay.com/api/v1/verify

Staging environment https://staging-api.swa-pay.com/api/v1/verify

JSON Object Payload Parameters

Parameter	Required	Description
phone	false	The member's phone number
country_code	false	The member's country code. Default JP
code	true	The OTP code was send vis SMS

JSON Object Response

Parameter	Description
id	The SWAPay user id
phone	The member's phone number
country_code	The member's country code. Default JP
phone_confirmed_at	The time when the phone is confirmed.

Obtain a list of Consumer

curl --location --request GET '{{server}}/api/v1/store/consumers?page_no=1&page_size=10' \
--header 'Authorization: meowmeowmeow'
The above command returns JSON structured like this:
{
  "data": [
    {
      "id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
      "display_name": "taphamkim hieu",
      "phone": null,
      "email": "hieutaphamkim89+1750@gmail.com",
      "role": "USER",
      "country_code": null,
      "provider": "EMAIL",
      "phone_e164": null,
      "operation_agency": null,
      "merchant": null,
      "owner": { "id": "af40eee0-81ad-4e29-a8ea-87603b3f8282", "display_name": "Merchant" },
      "store": { "id": "6a02b419-c8a4-4e85-bff2-2242686826f9", "store_name": "テスト", "office_name": "155" },
      "customer_id": null,
      "create_date": "2024-01-15T10:52:44.614+00:00",
      "gmo_status": "REGISTERED",
      "delete_flg": null,
      "first_name": "hieu",
      "last_name": "taphamkim",
      "user_name": null,
      "status": "ACTIVE",
      "order_id": null,
      "order_name": null,
      "user_wallet_address": null,
      "honorific_title": null
    },
    {
        "id": "c4a7e68b-c84c-459f-a3ed-3d2137d007e0",
        "display_name": "Ta Pham Kim Hieu",
        "phone": null,
        "email": "hieutaphamkim89+20240523_1@gmail.com",
        "role": "USER",
        "country_code": null,
        "provider": "EMAIL",
        "phone_e164": null,
        "operation_agency": null,
        "merchant": null,
        "owner": {"id": "af40eee0-81ad-4e29-a8ea-87603b3f8282","display_name": "Merchant"},
        "store": {"id": "6a02b419-c8a4-4e85-bff2-2242686826f9","store_name": "テスト","office_name": "155"},
        "customer_id": "hieutaphamkim89+20240527_1302@gmail.com",
        "create_date": "2024-05-23T03:21:54.259+00:00",
        "gmo_status": "REGISTERED",
        "delete_flg": null,
        "first_name": "Hieu",
        "last_name": "Ta Pham Kim",
        "user_name": null,
        "status": "ACTIVE",
        "order_id": null,
        "order_name": null,
        "user_wallet_address": null,
        "honorific_title": null
    },
    {
        "id": "065d6f2b-7310-4e92-b521-7707362c94ae",
        "display_name": null,
        "phone": null,
        "email": null,
        "role": "USER",
        "country_code": null,
        "provider": "CONSUMER",
        "phone_e164": null,
        "operation_agency": null,
        "merchant": null,
        "owner": {"id": "af40eee0-81ad-4e29-a8ea-87603b3f8282","display_name": "Merchant"},
        "store": {
            "id": "6a02b419-c8a4-4e85-bff2-2242686826f9",
            "store_name": "テスト",
            "office_name": "155"},
        "customer_id": "hieutaphamkim89+20240523_2@gmail.com",
        "create_date": "2024-05-23T06:55:11.356+00:00",
        "gmo_status": "REGISTERED",
        "delete_flg": null,
        "first_name": null,
        "last_name": null,
        "user_name": null,
        "status": "NOT_YET",
        "order_id": null,
        "order_name": null,
        "user_wallet_address": null,
        "honorific_title": null
    },
  ],
  "page_no": 1,
  "page_size": 10,
  "total_elements": 3,
  "total_pages": 1,
  "last": true
}
Abnormal

{
  "code": "E0401",
  "message": "Unauthorized",
  "errors": null
}
This endpoint returns a paginated list of consumers that belong to the current store context.

HTTP Request

GET /v1/store/consumers

Production environment https://api.swa-pay.com/api/v1/store/consumers

Staging environment https://staging-api.swa-pay.com/api/v1/store/consumers

Query Parameters

Parameter	Default	Description
page_no	1
page_size	10
keyword		Keyword to search consumers by user_id, email, phone (and related identifiers). Partial match supported.

Consumer Response Fields

Field	Type	Description
id	UUID	Consumer ID on SWAPay
display_name	String	Display name (nullable)
phone	String	Phone number (nullable)
email	String	Email (nullable)
role	String	User role (e.g., `USER`)
country_code	String	Country code (e.g., `JP`)
provider	String	Registration provider (`EMAIL`, `PHONE`, `CONSUMER`)
phone_e164	String	E.164 formatted phone (nullable)
owner	Object	Owner info `{ id, display_name }`
store	Object	Store info `{ id, store_name, office_name }`
customer_id	String	Customer ID on merchant system (nullable)
create_date	DateTime	Created time (ISO-8601)
gmo_status	String	GMO registration status (`REGISTERED`, `NOT_REGISTERED`)
status	String	Consumer status (`ACTIVE`, `NOT_YET`, …)
order_id	String	Latest order ID (nullable)
order_name	String	Latest order name/label (nullable)
user_wallet_address	String	Wallet address (nullable)
honorific_title	String	Honorific title (nullable)
delete_flg	Boolean	Deleted flag (nullable)
first_name	String	First name (nullable)
last_name	String	Last name (nullable)
user_name	String	Username (nullable)

Membership card

Card registration

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/cards' \
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MzY5MDk3MzF9.Tb4wsSMTITRLvV4PaHhgu_8QTPhGXuDktPIhd2pvmJM' \
--header 'Content-Type: application/json' \
--data-raw {
    "card_no": "5100 0000 0000 0115",
    "expire": "1231",
    "security_code": "123",
    "holder_name": "ta pham kim hieu",
    "user_id": "08f504d9-3cfc-4b78-bf61-8faddf42df15",
    "success_url": "https://swapay.co.jp/",
    "callback_url": "https://2446-115-78-15-4.ap.ngrok.io/gateway/receiving",
    "cancel_url": "https://swapay.co.jp/"
}

{
    "id": "ca0123b5-b402-47fb-bc04-2bf6fa71f1b3",
    "short_card_no": "*************115",
    "card_name": null,
    "expire": "12/31",
    "holder_name": "ta pham kim hieu",
    "card_type": "MASTER",
    "status": "ACTIVE",
    "security_code": null,
    "user_create": "08f504d9-3cfc-4b78-bf61-8faddf42df15",
    "create_date": "2025-10-22T04:44:38.231+00:00",
    "user_update": "08f504d9-3cfc-4b78-bf61-8faddf42df15",
    "update_date": "2025-10-22T04:44:38.231+00:00",
    "user": {
        "id": "08f504d9-3cfc-4b78-bf61-8faddf42df15",
        "first_name": null,
        "last_name": null,
        "email": null,
        "phone": null,
        "avatar": null,
        "confirmed": null,
        "role": "USER",
        "status": "NOT_YET",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": null,
        "display_gateway": "GMO_GATEWAY",
        "address": null,
        "invoice_business_registration_number": null,
        "company_name": null,
        "representative_name": null,
        "account_number": null,
        "user_id": null
    },
    "selected": false,
    "store": null,
    "gateway": null,
    "card_gateway_id": null,
    "pre_authorization": false,
    "transaction": {
        "id": "f7106ca2-e635-471e-9944-3071dfe56008",
        "pay_amount": 10.0,
        "currency": "JPY",
        "customer_id": null,
        "customer_order_id": null,
        "status": "AUTHENTICATING_3DS",
        "update_date": "2025-10-22T04:44:40.985+00:00",
        "create_date": "2025-10-22T04:44:40.985+00:00",
        "pay_method": "0",
        "pay_times": null,
        "order_id_csv": null,
        "actual_payment_date": null,
        "confirmed_at": null,
        "acs": "2",
        "acs_url": "https://simulator.test.fincode.jp/payment/Tds2StubCallback.idPass?transId=77974614-110b-4fb0-b314-9c117e3726bd&t=a_cXKnXjgqT4ukDBY_fgVE4Q",
        "redirect_url": "https://staging-api.swa-pay.com/api/v1/fincode/secure/authentication/f7106ca2-e635-471e-9944-3071dfe56008",
        "user_payment": {
            "id": "08f504d9-3cfc-4b78-bf61-8faddf42df15",
            "first_name": null,
            "last_name": null,
            "email": null,
            "phone": null,
            "affiliate_code": null,
            "display_name": null,
            "address": null
        },
        "state": null
    },
    "error": null
}

This endpoint will help you register the card information with the specified member.

HTTP Request

POST /v1/cards

Production environment https://api.swa-pay.com/api/v1/cards

Staging environment https://staging-api.swa-pay.com/api/v1/cards

JSON Object Payload Parameters

Parameter	Required	Description
user_id	true	The SWAPay user id
card_no	true	Credit card number
expire	true	Credit card expiration date - MMYY format
security_code	true	Security code - The 3- or 4-digit number printed on the card
holder_name	true	Credit card name
success_url	false	Redirect to `success_url` after successful payment
cancel_url	false	Redirect to `cancel_url` when buyer cancels the order
callback_url	false	JSON-formatted `POST` notification message will be sent to `callback_url` when order status is changed. If the callback is empty, we can send information to merchant's email.

Card Response Fields

Field	Type	Description
id	`UUID`	Card ID on SWAPay
short_card_no	`String`	Masked card number (last digits only).
card_name	`String`	Custom card label set by user (nullable)
expire	`String`	Expiry in `MM/YY` format
holder_name	`String`	Cardholder name (as registered)
card_type	`String`	Card brand (`VISA`, `MASTER`, `JCB`, `AMEX`, `DINERS`, …)
status	`String`	Card status (`ACTIVE`, `DELETED`)
user_create	`UUID`	Creator user ID
create_date	`DateTime`	Created time
user_update	`UUID`	Last updater user ID
update_date	`DateTime`	Last updated time
user	`Object`	Owner user info
selected	`Boolean`	`true` if this is the consumer’s default/selected card
store	`Object`	Store info *(nullable)
gateway	`Object`	Gateway info (nullable)
card_gateway_id	`String`	Gateway-side card identifier (nullable)
pre_authorization	`Boolean`	`true` if this card was successfully 3DS2 pre-authenticated at registration; `false` otherwise
transaction	`Object`	Present only when Pre-Authentication is enabled. Contains the 3DS2 authentication transaction to complete card registration (e.g., id, status, pay_amount = 10, acs, acs_url, redirect_url, timestamps, user_payment). Use redirect_url (recommended) or acs_url to complete the 3DS2 challenge. (nullable)
error	`Object`	Additional error payload when registration encounters an issue. Follows the standard error format { code, message, errors }. null on success. If not null, handle this instead of proceeding with transaction. (nullable)

Transaction Field

Field	Type	Description
`id`	UUID	ID of the transaction.
`pay_amount`	Double	Amount of the transaction.
`currency`	String	The currency used for payment. Default is `JPY`.
`customer_id`	String	The customer ID in the merchant system.
`customer_order_id`	String	The order ID in the merchant system.
`status`	String	Status of the payment request.
`acs`	String	Indicates whether to use 3D Secure authentication. `0`: Do not use 3D Secure authentication (default). `2`: Use 3D Secure 2.0 authentication.
`acs_url`	String	URL of the 3D Secure authentication page returned directly from the payment gateway. Used only when your system implements the entire 3D Secure authentication process.
`redirect_url`	String	3D Secure authentication URL provided by Swapay. This URL is customized to simplify integration and can be used as an alternative to `acs_url` if you prefer Swapay to handle part or all of the 3D Secure authentication flow.
`pay_method`	String	Payment method: `0`: Credit card payment.

Notes Raw PAN/CVV are not stored and are never returned by the API. If Pre-Authentication is enabled, the system will create a temporary order for ¥10, attempt a 3DS2 authentication + payment, and auto-refund that order on success. Cards that passed the initial 3DS2 pre-auth can later be used with either 3DS2 or No-3DS, depending on risk/routing settings.

Client flow (high level)

Register card via POST /v1/cards.
If the store has Pre-Authentication enabled, the API returns an AUTHENTICATING_3DS payload.
Redirect the user to redirect_url (recommended), or directly to acs_url, to complete the 3DS2 challenge.
On success, the temporary order (¥10) is paid and then auto-refunded.
The card appears in GET /v1/store/consumers/{consumer_id}/cards with pre_authorization = true. ### Tips
Use success_url / cancel_url to return the browser to your site after 3DS2.
Use callback_url for server-to-server confirmation if you want to finalize the UI without relying on browser redirects.

Card Remove

curl --location --request DELETE 'https://staging-api.swa-pay.com/api/v1/cards/{id}' \
--header 'Authorization: {store_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "06d43140-51d8-40a7-b457-221f46d74c23"
}'

{
    "id": "06d43140-51d8-40a7-b457-221f46d74c23",
    "short_card_no": "*************100",
    "card_name": null,
    "expire": "12/25",
    "holder_name": "LYBIA SOFT",
    "card_type": "VISA",
    "status": "DELETE",
    "security_code": null,
    "create_date": "2024-05-23T04:29:47.751+00:00",
    "update_date": "2024-05-27T05:50:38.670+00:00",
}

Remove card by card_id

HTTP Request

DELETE /v1/cards/{id}

Production environment https://api.swa-pay.com/api/v1/cards/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/cards/{id}

JSON Object Payload Parameters

Parameter	Required	Description
id	true	The SWAPay card id (UUID)

Response Fields

Field	Type	Description
id	UUID	Card ID on SWAPay System
card_seq	String	Card registration serial number
expire	String	Card expiration date (format MM/YY)
status	String	card status
holder_name	String	card holder
short_card_no	String	the masked value card number
card_type	String	card type

Get a list of cards

curl --location --request GET '{{server}}/api/v1/store/consumers/{consumer_id}/cards' \
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MDUzMTU5NDV9.xT3EFN3SC51hORCMEaSDeoA1KEGwGm7cAXdIFQtxr28'

> The above command returns JSON structured like this:
[
  {
    "id": "4cdfaa39-61e3-4cc4-8f68-a0d02bc91319",
    "short_card_no": "****************007",
    "card_name": null,
    "expire": "12/31",
    "holder_name": "ta pham kim hieu",
    "card_type": "MASTER",
    "status": "ACTIVE",
    "security_code": null,
    "user_create": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
    "create_date": "2025-10-19T06:10:15.774+00:00",
    "user_update": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
    "update_date": "2025-10-19T06:10:15.774+00:00",
    "user": {
      "id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
      "first_name": "hieu",
      "last_name": "taphamkim",
      "email": "hieutaphamkim89+1750@gmail.com",
      "phone": null,
      "avatar": null,
      "confirmed": null,
      "role": "USER",
      "status": "ACTIVE",
      "affiliate_code": null,
      "parent_id": null,
      "display_name": "taphamkim hieu",
      "display_gateway": "GMO_GATEWAY",
      "address": null,
      "invoice_business_registration_number": null,
      "company_name": null,
      "representative_name": null,
      "account_number": null,
      "user_id": null
    },
    "selected": true,
    "store": null,
    "gateway": null,
    "card_gateway_id": null,
    "pre_authorization": true
  },
  {
    "id": "9cd378b2-7086-4d69-b245-95b97f84f0da",
    "short_card_no": "****************000",
    "card_name": null,
    "expire": "12/31",
    "holder_name": "ta pham kim hieu",
    "card_type": "VISA",
    "status": "ACTIVE",
    "security_code": null,
    "user_create": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
    "create_date": "2025-10-19T06:10:48.553+00:00",
    "user_update": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
    "update_date": "2025-10-19T06:10:48.553+00:00",
    "user": {
      "id": "02eecc89-5ac8-4969-9e8f-d183fc8c84a4",
      "first_name": "hieu",
      "last_name": "taphamkim",
      "email": "hieutaphamkim89+1750@gmail.com",
      "phone": null,
      "avatar": null,
      "confirmed": null,
      "role": "USER",
      "status": "ACTIVE",
      "affiliate_code": null,
      "parent_id": null,
      "display_name": "taphamkim hieu",
      "display_gateway": "GMO_GATEWAY",
      "address": null,
      "invoice_business_registration_number": null,
      "company_name": null,
      "representative_name": null,
      "account_number": null,
      "user_id": null
    },
    "selected": false,
    "store": null,
    "gateway": null,
    "card_gateway_id": null,
    "pre_authorization": true
  }
]
> Abnormal
{
    "code": "E0208",
    "message": "User not found",
    "errors": null
}

This endpoint returns all saved cards of a given consumer within the current store context.

HTTP Request

GET /v1/store/consumers/{consumer_id}/cards

Production environment https://api.swa-pay.com/api/v1/store/consumers/{consumer_id}/cards

Staging environment https://staging-api.swa-pay.com/api/v1/store/consumers/{consumer_id}/cards

URL Parameters

Parameter	Description
consumer_id	The ID of the consumer

Error code list

Error Code	Meaning
E0401	Unauthorized (missing/invalid token)
E0403	Forbidden (no permission to this store/consumer)
E0208	User not found (invalid `consumer_id`)

Card Response Fields

Field	Type	Description
id	`UUID`	Card ID on SWAPay
short_card_no	`String`	Masked card number (last digits only).
card_name	`String`	Custom card label set by user (nullable)
expire	`String`	Expiry in `MM/YY` format
holder_name	`String`	Cardholder name (as registered)
card_type	`String`	Card brand (`VISA`, `MASTER`, `JCB`, `AMEX`, `DINERS`, …)
status	`String`	Card status (`ACTIVE`, `DELETED`)
user_create	`UUID`	Creator user ID
create_date	`DateTime`	Created time
user_update	`UUID`	Last updater user ID
update_date	`DateTime`	Last updated time
user	`Object`	Owner user info
selected	`Boolean`	`true` if this is the consumer’s default/selected card
store	`Object`	Store info *(nullable)
gateway	`Object`	Gateway info (nullable)
card_gateway_id	`String`	Gateway-side card identifier (nullable)
pre_authorization	`Boolean`	`true` if this card was successfully 3DS2 pre-authenticated at registration; `false` otherwise

Recurring billing

Create a new Recurring billing

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/store/recurring_billing' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pay_amount":5500,"pay_amount_in_month":1320,"currency":"JPY","subscribe_order_name":null,"user_id":"cbd1474e-a41c-4a1d-a6ce-b910157e95e2","date_start":"2024-09-25","date_end":"2024-12-18",
"first_payment_deadline": "2024-08-20",
"productions":
    [{"service_name":"service_test",
      "unit_price":100,
      "quantity":10,
      "tax_rate":"option_10",
      "sub_total":1100
      },
      {"service_name":"service_test_2",
       "unit_price":200,
        "quantity":20,
         "sub_total":4400,
         "tax_rate":"option_10"
       }
    ],
"initial":[{"service_name":"test_initial","unit_price":100,"quantity":12,"tax_rate":"option_10","sub_total":1320}],
"store_id":"955b8cc3-02dd-434e-927b-f718638536c1","invoice_number":"test","order_name":"test","monthly_payment_day":"12","description":"Description","date_payment":"2024-08-12","service_name_monthly":"service_test","service_name_initial":"test_initial"
}'

{
     "id": "8c646ba4-c7c5-4883-8d92-305ac9ca1da8",
    "pay_amount": 1320.0,
    "pay_next_month": null,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": null,
    "description": "Description",
    "consumer_id": "cbd1474e-a41c-4a1d-a6ce-b910157e95e2",
    "store": {
        "id": "955b8cc3-02dd-434e-927b-f718638536c1",
        "store_name": "store fincode n3 ",
        "office_name": "1",
        "gateway": "FIN_CODE_GATEWAY",
        "address": "1",
        "address2": "1Registered address",
        "postal_code": "1",
        "merchant": {
            "id": "95969926-0272-4021-82a9-2c58db5daadb",
            "first_name": null,
            "last_name": null,
            "email": "admin@nft-swapay.com",
            "phone": null,
            "avatar": null,
            "confirmed": null,
            "role": "ADMIN",
            "status": "ACTIVE",
            "affiliate_code": null,
            "parent_id": null,
            "display_name": "admin@nft-swapay.com",
            "display_gateway": "GMO_GATEWAY",
            "address": "HCM city",
            "invoice_business_registration_number": "s2201",
            "company_name": null,
            "representative_name": null,
            "account_number": null
        },
        "waiting_complete": false
    },
    "merchant": {
        "id": "95969926-0272-4021-82a9-2c58db5daadb",
        "first_name": null,
        "last_name": null,
        "email": "admin@nft-swapay.com",
        "phone": null,
        "avatar": null,
        "confirmed": null,
        "role": "ADMIN",
        "status": "ACTIVE",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": "admin@nft-swapay.com",
        "display_gateway": "GMO_GATEWAY",
        "address": "HCM city",
        "invoice_business_registration_number": "s2201",
        "company_name": null,
        "representative_name": null,
        "account_number": null
    },
    "agency": null,
    "subscribe": {
        "id": "7f4f941f-769b-43b3-8c06-721631e4986b",
        "subscribe_order_name": "test",
        "service_name_monthly": "service_test",
        "pay_amount": 5500.0,
        "service_name_initial": "test_initial",
        "initial_cost_amount": 1320.0,
        "date_start": "2024-09-25T00:00:00.000+00:00",
        "date_end": "2024-12-18T00:00:00.000+00:00",
        "pay_times": null,
        "monthly_payment_day": 12,
        "status": "TEMPORARY_SAVE",
        "consumer_name": "Hieu ta pham kim",
        "consumer_email": "hieutaphamkim89@gmail.com",
        "first_payment_deadline": "2024-08-20T00:00:00.000+00:00",
        "consumer_phone": "0964-47-7058"
    },
    "success_url": null,
    "cancel_url": null,
    "callback_url": null,
    "status": "WAITING_FOR_PAYMENT",
    "user_create": null,
    "create_date": "2024-09-25T08:10:12.180+00:00",
    "monthly_payment_date": "2024-08-20T00:00:00.000+00:00",
    "user_update": null,
    "update_date": "2024-09-25T08:10:12.180+00:00",
    "payment_url": "https://staging-user.swa-pay.com/payment/invoice?order=8c646ba4-c7c5-4883-8d92-305ac9ca1da8",
    "pay_method": null,
    "pay_times": null,
    "consumer_email": "hieutaphamkim89@gmail.com",
    "consumer_phone": null,
    "user_payment": null,
    "card_seq": null,
    "actual_payment_date": null,
    "confirmed_at": null,
    "pay_amount_fees": null,
    "actual_pay_amount": null,
    "card_type": null,
    "refunded_date": null,
    "fee_detail": null,
    "gmo_order_id": null,
    "error": null,
    "transaction_histories": null,
    "system_logs": null,
    "nft_evidence": null,
    "productions": [
        {
            "id": "a0ec2f11-2d22-43e7-84a3-aaa6664aa885",
            "order_id": "8c646ba4-c7c5-4883-8d92-305ac9ca1da8",
            "subscribe_order_id": "7f4f941f-769b-43b3-8c06-721631e4986b",
            "service_name": "test_initial",
            "unit_price": 100.0,
            "quantity": 12,
            "sub_total": 1320.0,
            "tax_rate": "option_10",
            "tax_value": "10",
            "sub_amount_untaxed": 1200.0,
            "flag_init": false
        }
    ],
    "tax_invoice": null,
    "order_name": "test",
    "expired_date": null,
    "consumer_name": null,
    "title": "test",
    "gateway": "FIN_CODE_GATEWAY",
    "authenticating_date": null,
    "status_request": null,
    "reason_request": null,
    "merchant_response": null,
    "date_request": null,
    "user_request": null,
    "date_response": null,
    "user_response": null,
    "store_qrhistory": null,
    "short_card_no": null,
    "nft": null,
    "issued_date": "2024-09-25T08:10:12.180+00:00",
    "invoice_number": null,
    "honorific_title": null,
    "amount_untaxed": null,
    "amount_taxed": null,
    "payment_app_url": "https://staging-api.swa-pay.com/gateway/payment/8c646ba4-c7c5-4883-8d92-305ac9ca1da8",
    "create_role": null,
    "payment_fees": null,
    "fee_tax": null,
    "tax_rate": null,
    "transaction_fee": null,
    "sales_processing_fee": null,
    "selected_payment_type": "SUBSCRIPTION",
    "selected_installment_term": null
}

{
    "code": "101",
    "message": "Missing amount",
    "errors": null
}

This endpoint will help you to start a recurring transaction

HTTP Request

POST /v1/store/recurring_billing

Production environment https://api.swa-pay.com/api/v1/store/recurring_billing

Staging environment https://staging-api.swa-pay.com/api/v1/store/recurring_billing

JSON Object Payload Parameters

Parameter	Type	Required	Description
pay_amount	Double	true	Recurring payment amount
pay_amount_in_month	Double	true	The amount paid in the first period (in current month)
currency	String	false	The currency used for payment. Default is JPY
description	String	false	Description of the transaction
customer_id	String	false	The customer id on merchant system
user_id	String	false	SWAPay user id (if the user_id is submitted, the customer_id is not needed)
customer_order_id	String	false	The order id on merchant systems
date_payment	DateTime	false	When to make payment for the first time
date_start	DateTime	false	Time to start the recurring payment
date_end	DateTime	false	when you want to stop paying in the future
success_url	String	false	Redirect to `success_url` after successful payment
callback_url	String	false	JSON-formatted `POST` notification message will be sent to `callback_url` when order status is changed. If the callback is empty, we can send information to merchant's email.
cancel_url	String	false	Redirect to `cancel_url` when buyer cancels the order
first_payment_deadline	DateTime	false	processing date first payment

Order Response Fields

Field	Type	Description
id	UUID	Payment request ID on NFT SWAP System
pay_amount	Double	Total amount to be paid
currency	String	The currency used for payment. Default is JPY
customer_id	String	The customer id on merchant system
user_id	String	false
customer_order_id	String	The order id on merchant systems
description	String	Description of the transaction
store	Object Store
merchant	Object Merchant
success_url	String	Redirect to `success_url` after successful payment
cancel_url	String	Redirect to `cancel_url` when buyer cancels the order
callback_url	String	JSON-formatted `POST` notification message will be sent to `callback_url` when order status is changed. If the callback is empty, we can send information to merchant's email.
status	String	Status of Payment request
pay_method	String
payment_url	String	The customer will process the payment at this site.
pay_times	Number
update_date	DateTime
create_date	DateTime
selected_payment_type	String	Enum: "SUBSCRIPTION"
selected_installment_term	String or null

Update a Recurring billing

curl --location --request PUT 'https://staging-api.swa-pay.com/api/v1/store/recurring_billing/b87395d6-e334-43be-bd72-800053c53283' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
    "monthly_payment_day": "6",
    "date_start": "2025-07-08",
    "date_end": "2027-07-03",
     "description": "Change payment day from 5 to 6 "
}'

{
    "id": "4a03c284-e139-4f62-94a6-6e04f5208c85",
    "subscribe_order_name": null,
    "service_name_monthly": null,
    "pay_amount": 8000.0,
    "service_name_initial": null,
    "initial_cost_amount": null,
    "first_payment_deadline": null,
    "date_start": "2025-07-04T10:00:00.000+00:00",
    "date_end": "2027-07-03T00:00:00.000+00:00",
    "pay_times": null,
    "monthly_payment_day": 6,
    "status": "WAITING_FOR_PAYMENT",
    "consumer_name": null,
    "consumer_email": null,
    "consumer_phone": null,
    "store": {
        "id": "955b8cc3-02dd-434e-927b-f718638536c1",
        "store_name": "store fincode n3",
        "office_name": "1",
        "gateway": "FIN_CODE_GATEWAY",
        "address": "HCM",
        "address2": "1Registered address",
        "postal_code": "1",
        "merchant": {
            "id": "95969926-0272-4021-82a9-2c58db5daadb",
            "first_name": "Admin",
            "last_name": "",
            "email": "admin@nft-swapay.com",
            "phone": null,
            "avatar": null,
            "confirmed": null,
            "role": "ADMIN",
            "status": "ACTIVE",
            "affiliate_code": "Abcd1234",
            "parent_id": null,
            "display_name": "Admin",
            "display_gateway": "GMO_GATEWAY",
            "address": "HCM city",
            "invoice_business_registration_number": "s2203",
            "company_name": null,
            "representative_name": null,
            "account_number": null
        },
        "trading_type": "REGULAR_PAYMENT",
        "receipt_enabled": true,
        "send_payment_success_email": true
    },
    "user": {
        "id": "4f301013-4e7f-4d5c-8254-f1dc8200bd77",
        "first_name": "Hieu",
        "last_name": "ta pham kim",
        "email": "hieutaphamkim89@gmail.com",
        "phone": "0964477058",
        "avatar": null,
        "confirmed": null,
        "role": "USER",
        "status": "ACTIVE",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": "ta pham kim Hieu",
        "display_gateway": "GMO_GATEWAY",
        "address": "Ho Chi Minh",
        "invoice_business_registration_number": null,
        "company_name": null,
        "representative_name": null,
        "account_number": null
    },
    "merchant": {
        "id": "95969926-0272-4021-82a9-2c58db5daadb",
        "first_name": "Admin",
        "last_name": "",
        "email": "admin@nft-swapay.com",
        "phone": null,
        "avatar": null,
        "confirmed": null,
        "role": "ADMIN",
        "status": "ACTIVE",
        "affiliate_code": "Abcd1234",
        "parent_id": null,
        "display_name": "Admin",
        "display_gateway": "GMO_GATEWAY",
        "address": "HCM city",
        "invoice_business_registration_number": "s2203",
        "company_name": null,
        "representative_name": null,
        "account_number": null
    },
    "currency": "JPY",
    "create_date": "2025-07-02T12:19:51.454+00:00",
    "description": "Change payment day from 5 to 6 ",
    "productions": null,
    "initial": null,
    "tax_invoice": null,
    "amount_untaxed": null,
    "amount_taxed": null,
    "tax_invoice_initial": null,
    "amount_untaxed_initial": null,
    "amount_taxed_initial": null,
    "date_cancel": null
}

This endpoint will help you to change the payment details of transactions.

HTTP Request

PUT /v1/store/recurring_billing/{id}

Production environment https://api.swa-pay.com/api/v1/store/recurring_billing/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/store/recurring_billing/{id}

JSON Object Payload Parameters

Parameter	Type	Required	Description
date_start	DateTime	false	Start date of the recurring payment period.
date_end	DateTime	false	End date of the recurring payment period.
monthly_payment_day	Number	false	Day of the month when payment is charged.
description	String	false	Optional description of the recurring plan.

Order Response Fields

Field	Type	Description
id	UUID	ID of the subscription order.
subscribe_order_name	String	Name of the subscription order.
service_name_monthly	String	Name of the monthly service.
pay_amount	Double	Amount to be paid monthly.
service_name_initial	String	Name of the initial service or setup.
initial_cost_amount	Double	Initial setup cost or one-time fee.
first_payment_deadline	DateTime	Deadline for the first payment.
date_start	DateTime	Start date of the recurring payment period.
date_start	DateTime	End date of the recurring payment period.
currency	String	The currency used for payment. Default is JPY
user	Object User Paymment	false
description	String	Description of the transaction (e.g. purpose or subscription details).
store	Object Store	Store information.
merchant	Object Merchant	Merchant information.
monthly_payment_day	Number	Day of the month when the payment is charged.
status	String	Status of the subscription order.
consumer_name	String	Name of the consumer.
consumer_email	String	Email address of the consumer.
consumer_phone	String	Phone number of the consumer.
update_date	DateTime	Date when the record was last updated.
create_date	DateTime	Date when the record was created.
productions	Object productions	Information about the subscribed products or services.
tax_invoice	Double	Tax amount (monthly).
amount_untaxed	Double	Monthly payment amount before tax.
amount_taxed	Double	Monthly payment amount including tax.
tax_invoice_initial	Double	Tax amount of the initial cost.
amount_untaxed_initial	Double	Initial cost before tax.
amount_taxed_initial	Double	Initial cost including tax.
date_cancel	DateTime	Date when the subscription was canceled.

Subscription order Status

Status Code	Meaning
TEMPORARY_SAVE	The subscription order has been temporarily saved but not yet submitted for payment.
WAITING_FOR_PAYMENT	The initial payment was completed, and the subscription is active. The system is now waiting for the upcoming recurring payments (e.g., monthly billing).
COMPLETE	The recurring billing cycle has finished. All scheduled payments have been completed, and the subscription is now closed.
CANCEL	The subscription order was canceled by the user or merchant before payment was completed (i.e., while in TEMPORARY_SAVE or WAITING_FOR_PAYMENT status).
ERROR	A failure occurred during the payment process, and the transaction could not be completed.

Making a payment using a card number

curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/store/recurring_billing/payment' \
--header 'Authorization: meowmeowmeow.' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "c2b5512c-7ef2-4590-bfb7-3eb2874b2187",
    "card_no": "4111111111111111",
    "expire": "1225",
    "security_code": "123",
    "holder_name": "LYBIA SOFT",
    "user_id": "af40eee0-81ad-4e29-a8ea-87603b3f8282"
}'

{
    "id": "c2b5512c-7ef2-4590-bfb7-3eb2874b2187",
    "pay_amount": 700.0,
    "currency": "JPY",
    "customer_id": null,
    "customer_order_id": null,
    "status": "COMPLETE",
    "update_date": "2022-08-12T14:13:27.735+00:00",
    "create_date": "2022-08-12T14:13:22.283+00:00",
    "pay_method": null,
    "pay_times": null,
    "order_id_csv": "c45f6d4f-9551-43ce-85db-ff9dd839706e"
}

{
    "code": "303",
    "message": "The status of the transaction does not allow this action",
    "errors": null
}

This endpoint will help you to payment for a recurring transaction.

HTTP Request

POST /v1/store/recurring_billing/payment

Production environment https://api.swa-pay.com/api/v1/store/recurring_billing/payment

Staging environment https://staging-api.swa-pay.com/api/v1/store/recurring_billing/payment

JSON Object Payload Parameters (Payment with new card)

Parameter	Required	Description
id	true	ID of the transaction
card_no	true	credit card number
expire	true	Credit card expiration date - MMYY format
security_code	true	security code - The 3- or 4-digit number printed on the card
holder_name	true	Credit card name
user_id	true	The ID of the customer who will be the purchaser.

JSON Object Payload Parameters (Payment with member)

Parameter	Required	Description
id	true	ID of the transaction
card_id	true	The ID of the card used for this payment.
user_id	true	The ID of the customer who will be the purchaser.

Termination of subscription

curl --location --request DELETE 'https://staging-api.swa-pay.com/api/v1/store/recurring_billing/9346119c-2a27-4697-ada9-bab6873c3d69' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json'

{
    "id": "9346119c-2a27-4697-ada9-bab6873c3d69",
    "subscribe_order_name": "test",
    "service_name_monthly": "test",
    "pay_amount": 1100.0,
    "service_name_initial": "test init",
    "initial_cost_amount": 5500.0,
    "first_payment_deadline": "2024-10-19T17:00:00.000+00:00",
    "date_start": "2024-11-24T00:00:00.000+00:00",
    "date_end": null,
    "pay_times": null,
    "monthly_payment_day": 24,
    "status": "CANCEL",
    "consumer_name": "ta pham kim Hieu",
    "consumer_email": "hieutaphamkim89@gmail.com",
    "consumer_phone": "0964-47-7058",
    "store": {
        "id": "955b8cc3-02dd-434e-927b-f718638536c1",
        "store_name": "store fincode n3",
        "office_name": "1",
        "gateway": "FIN_CODE_GATEWAY",
        "address": "1",
        "address2": "1Registered address",
        "postal_code": "1",
        "merchant": {
            "id": "95969926-0272-4021-82a9-2c58db5daadb",
            "first_name": null,
            "last_name": null,
            "email": "admin@nft-swapay.com",
            "phone": null,
            "avatar": null,
            "confirmed": null,
            "role": "ADMIN",
            "status": "ACTIVE",
            "affiliate_code": null,
            "parent_id": null,
            "display_name": "admin@nft-swapay.com",
            "display_gateway": "GMO_GATEWAY",
            "address": "HCM city",
            "invoice_business_registration_number": "s2201",
            "company_name": null,
            "representative_name": null,
            "account_number": null
        },
        "trading_type": "TEMPORARY_SALES_PAYMENT"
    },
    "user": {
        "id": "4f301013-4e7f-4d5c-8254-f1dc8200bd77",
        "first_name": "Hieu",
        "last_name": "ta pham kim",
        "email": "hieutaphamkim89@gmail.com",
        "phone": "0964-47-7058",
        "avatar": null,
        "confirmed": null,
        "role": "USER",
        "status": "ACTIVE",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": "ta pham kim Hieu",
        "display_gateway": "GMO_GATEWAY",
        "address": "Ho Chi Minh",
        "invoice_business_registration_number": null,
        "company_name": null,
        "representative_name": null,
        "account_number": null
    },
    "merchant": {
        "id": "95969926-0272-4021-82a9-2c58db5daadb",
        "first_name": null,
        "last_name": null,
        "email": "admin@nft-swapay.com",
        "phone": null,
        "avatar": null,
        "confirmed": null,
        "role": "ADMIN",
        "status": "ACTIVE",
        "affiliate_code": null,
        "parent_id": null,
        "display_name": "admin@nft-swapay.com",
        "display_gateway": "GMO_GATEWAY",
        "address": "HCM city",
        "invoice_business_registration_number": "s2201",
        "company_name": null,
        "representative_name": null,
        "account_number": null
    },
    "currency": "JPY",
    "create_date": "2024-10-24T15:00:58.483+00:00",
    "description": "test",
    "productions": null,
    "initial": null,
    "tax_invoice": null,
    "amount_untaxed": null,
    "amount_taxed": null,
    "tax_invoice_initial": null,
    "amount_untaxed_initial": null,
    "amount_taxed_initial": null
}

This endpoint will help you to change the payment details of transactions.

HTTP Request

DELETE /v1/store/recurring_billing/{id}

Production environment https://api.swa-pay.com/api/v1/store/recurring_billing/{id}

Staging environment https://staging-api.swa-pay.com/api/v1/store/recurring_billing/{id}

JSON Object Payload Parameters

Parameter	Type	Required	Description
id	UUID	true	ID of the transaction

Errors

{
    "code": "101",
    "message": "Missing amount",
    "errors": null
}

HTTP Status codes:

Status Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The api requested is hidden for special roles.
404	Not Found -- The endpoint could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The SWAPAY API Error code list

Error Code	Meaning
101	Missing amount
303	The status of the order does not allow payment
304	The payment request ID is invalid
401	Incorrect password or email
403	Invalid authorization code
500	Internal error server
E0001	Passwords do not match
E0002	Change passwords do not succeeded
E0003	Password and New Password is same
E0004	Password not correct
E0005	Date format not correct
E0006	User does not have permission to access
E0007	Merchant does not exists
E0008	Password confirmation cannot be empty
E0009	Passwords do not match
E0010	Email is already used
E0011	User register not success
E0012	User does not active
E0013	User does not exists
E0014	Email or password not correct
E0015	Email is required
E0016	Username is required
E0017	Merchant contract is existed
E0018	An error occurred, register merchant contract is not success
E0019	Customer ID is already used
E0020	Delete merchant contract failed
E0021	Merchant Contract does not exist
E0022	Merchant isn't activated
E0013	Merchants don't own store
E0100	Regenerate token store do not succeeded
E0101	The store is not found
E0102	Update store is failed
E0103	Store has deleted, can not update.
E0104	Delete store is failed
E0105	Active store is failed
E0106	Store isn't activated
E0107	Store id required
E0108	Store is active, merchant is not permission not update
E0200	Update status order is not success
E0201	Order status not change
E0202	Missing pay times
E0203	Missing amount
E0204	Missing user ID
E0205	Invalid user ID
E0206	Transaction is not continuous payment
E0207	Create order is failed

Credit card payment error code

You can check at GMO Mulpay Docs.