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
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "https://staging-api.swa-pay.com" \
-H "Authorization: meowmeowmeow"
Make sure to replace
meowmeowmeow
with your API key.
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
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
}'
The above command returns JSON structured like this:
{
"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
}
Abnormal
{
"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
}'
The above command returns JSON structured like this:
{
"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'
The above command returns JSON structured like this:
[
{
"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'
The above command returns JSON structured like this:
{
"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
Each JSON-formatted
POST
notification message like this:
{
"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
}
We'll let you know when a transaction changes status via callback_url
.
Callback Response Fields
Field | Type | Description |
---|---|---|
id | ||
pay_amount | ||
currency | ||
customer_id | ||
customer_order_id | ||
status | ||
pay_method | ||
pay_times | ||
update_date | ||
create_date |
Settlement - No 3DS
Make a payment by communicating with the card company.
When making a payment using a token
When paying with a member ID
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"
}'
The above command returns JSON structured like this:
{
"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
}
Abnormal
{
"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"
}'
The above command returns JSON structured like this:
{
"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"
}
Abnormal
{
"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 and the FinCode 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": "09e68717-391a-4b01-87cb-0ccd7305eb8e",
"card_no": "4100000000000100",
"expire": "12/25",
"security_code": "123",
"holder_name": "LYBIA SOFT"
}'
The above command returns JSON structured like this:
{
"id": "09e68717-391a-4b01-87cb-0ccd7305eb8e",
"pay_method": "0",
"acs": "2",
"acs_url": "https://3c80-2405-4802-9119-ab90-e86d-6d5a-d791-666c.ap.ngrok.io/gateway/3ds/09e68717-391a-4b01-87cb-0ccd7305eb8e/3b79e76d924d7bdd29b10e001e08d500",
"md": "3b79e76d924d7bdd29b10e001e08d500"
}
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 |
acs | String | 2 => (3DS2.0) |
acs_url | String | 3DS password input screen URL |
md | String | Transaction ID on GMO System |
pay_method | String | 0 => (Credit card payment) |
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"
}'
The above command returns JSON structured like this:
{
"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"
}'
The above command returns JSON structured like this:
{
"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"
}'
The above command returns JSON structured like this:
{
"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
}
Abnormal
{
"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 |
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 |
String | ||
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'
The above command returns JSON structured like this:
{
"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"
}
Abnormal
{
"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"
}'
The above command returns JSON structured like this:
{
"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"
}
Abnormal
{
"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 |
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'
The above command returns JSON structured like this:
{
"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"
}
Abnormal
{
"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"
}'
The above command returns JSON structured like this:
{
"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. |
Membership card
Card registration
curl --location --request POST 'https://staging-api.swa-pay.com/api/v1/cards' \
--header 'Authorization: meowmeowmeow' \
--header 'Content-Type: application/json' \
--data-raw '{
"user_id": "9af4f665-9869-4c95-99ca-51d14a32d50f",
"card_no": "4100000000000100",
"expire": "1225",
"security_code": "123",
"holder_name": "LYBIA SOFT"
}'
The above command returns JSON structured like this:
{
"id": "35f7282f-c5c5-4d24-9c56-e5495f07cab4",
"card_seq": "3",
"short_card_no": "*************100",
"card_name": null,
"expire": null,
"holder_name": null,
"forward": "2a99662"
}
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 | false | 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 |
Response Fields
Field | Type | Description |
---|---|---|
id | UUID | Card ID on SWAPay System |
card_seq | String | Card registration serial number |
forward | String | Destination code |
short_card_no | String | the masked value card number |
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"
}'
The above command returns JSON structured like this:
{
"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 |
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"
}'
The above command returns JSON structured like this:
{
"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
}
Abnormal
{
"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 '{
"pay_amount": 1000
}'
The above command returns JSON structured like this:
{
"id": "b87395d6-e334-43be-bd72-800053c53283",
"description": "Recurring Billing",
"pay_amount": 1000.0,
"pay_amount_in_month": 700.0,
"currency": "JPY",
"card_seq": null,
"short_card_no": null,
"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",
"customer_id": null,
"status": "WAITING_FOR_PAYMENT",
"date_payment": "2022-08-13T02:17:04.635+00:00",
"date_start": "2022-08-01T10:00:00.000+00:00",
"date_end": null,
"date_cancel": null,
"user_create": null,
"create_date": "2022-08-13T02:17:04.635+00:00",
"user_update": null,
"update_date": "2022-08-13T02:17:04.635+00:00",
"file_path": null,
"file_path_history": null
}
This endpoint will help you to change the payment details of transactions.
HTTP Request
PUT https://staging-api.swa-pay.com/api/v1/store/recurring_billing/{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 |
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"
}'
The above command returns JSON structured like this:
{
"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"
}
Abnormal
{
"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. |
Errors
The error response:
{
"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.