ShopeePay Integrationarrow-svg
Get Started with ShopeePay
API Documentationsarrow-svg
Customer Presented ModeMerchant Presented ModeCheckout with ShopeePayAccount LinkingLink & PaySubscriptionAuth & CaptureInvalidate QRInvalidate OrderRefund a PaymentNotify Transaction StatusCheck Transaction Status
Common ObjectsRevision History

Link & Pay

Merchant Workflow

To initiate the payment in this scenario, the merchant needs to complete the following steps:

  1. Allow the user to complete account linking and store the returned access token

  2. Optional: to retrieve coin redemption info, for displaying on the merchant checkout page

  3. (If API-Based) Call Get Payment Methods API to retrieve the user's available payment methods for this transaction

  4. Initiate a payment request with the Direct Payment API when the user pays

  1. Before initiating a payment request, the merchant can call the two endpoints below based on the use cases:
    • Get Payment Methods: ShopeePay will return the user's available payment methods for a given transaction, for the merchant to display for user's selection.
    • Get Coin Redemption: ShopeePay will return the user's Shopee Coin redemption rules and Coin amount, should the merchant wish to display this information.
  2. Merchant calls the Direct Payment endpoint to initiate the payment. ShopeePay will return a redirect_url for the merchant to redirect users to ShopeePay's FE should there be further payment confirmation or verification required. If the user has selected a certain payment method on the merchant's FE, merchant must inform ShopeePay of this in the request.
  3. ShopeePay processes the payment and returns the user back to the merchant’s page.
  4. ShopeePay will send an asynchronous message via Notify Transaction Status endpoint to inform merchants on the payment result.
  5. Merchants can also call the Check Transaction Status endpoint to query the status of the transaction.
    • If the response code is "Success", merchant can mark this transaction as successful.
    • If the response code is "Failed", merchant can mark this transaction as failed.
    • If the transaction is in a processing status, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes up to 24 hours.
    • If the transaction has no response, please retry the request at an incremental time range of every 5 seconds (e.g., 5 seconds, 10 seconds, 15 seconds, and so on) up to a maximum of 100 seconds. If there is no response after 100 seconds, please retry the request at an incremental time range of every 5 minutes up to 24 hours.
    • If customer can show evidence of payment success on their payment app, merchant may choose to consider payment as successful and wait for reconciliation process on T+1 to settle discrepancies with ShopeePay, if any.

API Documentation

Get Payment Methods

Mandatory when the merchant maintains their own end-to-end checkout flow (API-Based flow).

Use this endpoint to fetch the user's available payment methods for the transaction. Once ShopeePay returns the information to the merchant, merchant should display each method alongside their necessary information on the merchant's FE page, for the user to select.

  • URL: "/v4/merchant-host/payment-methods/get"

Request Parameters

request_id

stringRequired
Unique identifier of the API request.

access_token

stringRequired
The access token that was obtained from ShopeePay via the Get Access Token API, representing the user's authorization.

merchant_ext_id

stringRequired
Unique identifier of the merchant in the merchant's system.

store_ext_id

stringRequired
Unique identifier of the store in the merchant's system.

amount

int64
The order amount. If this parameter is provided, we will precheck the availability of each payment method using this amount.

Note that the value of this parameter is inflated by 100. For example, if the currency is SGD and the amount is $12.34, set the value of this parameter to 1234. If the currency is VND and the amount is 123, set the value of this parameter to 12300.

language

string
Language in which the linked payment methods are displayed. The default is English.

Possible values:

  • Indonesian : id
  • English: en
  • Malay: ms
  • Thai: th
  • Vietnamese:vi

additional_info

object
Show child child parameters

field1

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field2

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field3

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

device_info

Object
Show child child parameters

device_id

String
Merchant's unique identifier for the user's device.

device_brand

String
Brand of the device, e.g. 'Apple', 'Samsung'.

device_model

String
Model of the device, e.g. 'iPhone 14', 'Galaxy S24'.

os_version

String
Operating system and version, for example: 'iOS 16', 'Android 14'.

iosudid

String
Unique device identifier for iOS devices.

imei

String
Unique identifier such as IMEI (for compatible devices).

verification_completion_method

String
Verification that happens within merchant app.

Potential enum:

  • none
  • biometric
  • pin
  • password
  • pattern
  • other

device_first_login_at

String
Earliest timestamp when this device first logged in to the merchant app.

risk_tags

Object
Show child child parameters

jailbroken

Boolean
true if jailbroken (iOS) or rooted (Android)

enabled_emulator

Boolean
true if the app is running in an emulator environment (for example Genymotion).

enabled_remote_control

Boolean
true if remote access / remote control tools (for example TeamViewer, scrcpy) are active

modified_gps

Boolean
true if GPS appears tampered or inconsistent (possible GPS modification).

installed_fake_gps_app

Boolean
true if known fake-GPS apps are installed on the device.

gps

Object
Show child child parameters

latitude

Float
Device latitude at the time of transaction.

longitude

Float
Device longitude at the time of transaction.

location

String
Human-readable GPS location, for example: country and city. IP address of the device at the time of transaction.

device_ip

String
IP address of the device at the time of transaction.

device_risk_score

String
Risk score assigned by merchant’s system.
Potential enum values: high, medium, low.

additional_info

String
Any extra device-related risk information not covered by the structured fields.

user_account

Object
Show child child parameters

user_id

String
Identifier that uniquely represents the user in the merchant’s system.

phone_number

String
At least one of phone_number, email, or username must be provided.

email

String
At least one of phone_number, email, or username must be provided.

username

String
At least one of phone_number, email, or username must be provided.

account_registration_time

String
Timestamp when the user account was first registered with the merchant.

account_risk_score

String
Risk score assigned to the user account by the merchant.
Potential enum values: high, medium, low.

merchant_account

Object
Show child child parameters

merchant_name

String
Merchant business name

merchant_id

String
Identifier for each unique merchant onboarded by payment facilitator (most aggregated level)

merchant_mcc

String
Merchant Category Code (MCC). Leave blank if the external merchant differentiates only by store level.

merchant_address

Object
Show child child parameters

region

String
Registered address of the merchant. Leave blank if you only differentiate at store/outlet level.

state

String

city

String

address

String

postal_code

String

store

Object
Show child child parameters

store_name

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_id

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_mcc

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_address

Object
Show child child parameters

region

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

state

String

city

String

address

String

postal_code

String

order_details

Object
Show child child parameters

payment_initiation

String
Indicates how the payment is initiated.

Potential value:

  • MERCHANT_QR_PROPRIETARY: Merchant-presented proprietary QR scanned by the customer to initiate payment.
  • MERCHANT_QR_NATIONAL: Merchant-presented national / standardized QR scanned by the customer to initiate payment.
  • CUSTOMER_QR_PROPRIETARY: Customer-presented proprietary QR scanned by the merchant to initiate payment.
  • CUSTOMER_QR_NATIONAL: Customer-presented national / standardized QR scanned by the merchant to initiate payment.
  • ONLINE_CHECKOUT: Online checkout where the customer confirms an order and pays with a non-QR method (card, wallet, giro, etc.).
  • SUBSCRIPTION: Recurring or scheduled billing initiated automatically
  • TRANSFER: Fund transfer between accounts (for example, P2P or internal balance movement) without an order/cart.

description

String
Free-text description of the charge.

shipping_address

Object
Show child child parameters

region

String
Shipping address where goods are delivered. Mandatory for online merchants except for purely virtual goods.

state

String

city

String

address

String

postal_code

String

merchant_additional_info

String
Additional merchant-specific information for this order, if any.

items

Object
Show child child parameters

item_name

String
item name user bought in online platform or App.

item_quantity

Int
item number user bought in online platform or App.

item_currency

String
item currency Example, SGD.

item_amount

Int64
item amount

item_category

String
Category of the item (merchant-defined taxonomy).

qr_details

Object
Show child child parameters

qr_type

String
Potential values: 'static' or 'dynamic'.

qr_create_time

String
Creation timestamp for dynamic QR codes.

qr_source

String
How the user submitted the QR for payment.

Potential values: 'scan'; 'upload'

national_qr_payload

String
Raw national QR payload string as defined by the national QR standard.

Sample API Request

{
        "request_id": "input-unique-request-id-here",
        "merchant_ext_id": "external-merchant",
        "store_ext_id":"external-store",
        "access_token": "uXjWuhPGepS9tntoC8kTK5er6DlbUiGeSJDt53",
        "amount":  1000000,
        "currency": "IDR"
}
arrow-svg

Copy

Response Parameters

request_id

stringRequired
Echoing the request_id value from the request.

errcode

int32Required
Error code to specify the error returned. Refer to Response Code.

debug_msg

stringRequired
A description of the errcode.

saved_payment_methods

arrayRequired
An array of the user's payment methods linked to ShopeePay.
Show child child parameters

payment_method_type

stringRequired
Type of payment method. Refer to Payment Method Type.

display_name

stringRequired
Display name of the method (e.g., ShopeePay Balance, DBS Bank, HSBC).

This will be returned in the language provided by the merchant in the API request when applicable.

description

string
Provides a short, user-facing description of the payment method, highlighting key features or benefits.

icon_url

stringRequired
The icon image of the payment method, to be displayed on the merchant's frontend.

Note: For Credit / Debit Cards, the icon is the network's icon (e.g. Visa / Mastercard).

saved_payment_method_id

stringRequired
A unique identifier to indicate this particular payment method option.

This can be used when the merchant wants to save the user's linked methods on file and customized the default selection logic.

payment_option_reference

stringRequired
A unique identifier to indicate this particular payment method option, to be passed in the Direct Payment API request.

This hashed value consists of transaction information like the payment method option (e.g. which specific cards that the user chose), transaction fees and payable amount.

payment_method_availability

objectRequired
Indicates the availability of the payment method.
Show child child parameters

is_available

booleanRequired
Possible values:

  • true: the payment method is available and may become a successful payment.
  • false: The payment method is unavailable. Do not allow users to select this payment method.

unavailable_reason

string
Reason of unavailable payment method. E.g. Insufficient wallet balance.

This can be displayed on the merchant's frontend as needed. If the payment method is available, this field will be hidden.

payment_method_details

objectRequired
Show child child parameters

ewallet

object
Value is ewallet if payment_method_type = ewallet
Show child child parameters

available_balance

intRequired
Available wallet balance of the user.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

card

object
Value is card if payment_method_type = card
Show child child parameters

last_4digits

stringRequired
Last 4 digits of the card number.

card_type

stringRequired
Possible values:

  • credit_card
  • debit_card

network

stringRequired
Network of the card.

Possible values:

  • visa
  • mastercard
  • amex
  • jcb
  • discovery

giro_bank

object
Value is giro_bank if payment_method_type = giro_bank
Show child child parameters

last_4digits

stringRequired
Last 4 digits of the linked bank account.

spay_later

object
Value is spay_later if payment_method_type = spay_later
Show child child parameters

credit_balance

intRequired
Available SpayLater credit balance of the user.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

compliance_notices

array
This parameter consists of multiple objects, each representing a mandatory compliance document to be displayed on the merchant's frontend.
Show child child parameters

content

objectRequired
The actual content of the copywriting.
Show child child parameters

content_type

stringRequired
Possible values:

  • text: for plain text
  • link: for text with hyperlink

text

stringRequired
The display text for the content.

bold

boolean
Indicates whether the text should be emphasized in bold.

url

string
The URL for the link. This parameter is only returned when content type is link.

spaylater_options

arrayRequired
The available installment options using SPayLater for this transaction.
Show child child parameters

saved_payment_method_id

stringRequired
A unique identifier to indicate this particular payment method option.

payment_option_reference

stringRequired
A unique identifier to indicate this particular payment method option, to be passed in the Direct Payment API request.

display_name

stringRequired
Display name of the installment option.

payment_method_availability

objectRequired
Indicates the availability of the payment method.
Show child child parameters

is_available

booleanRequired
Possible values:

  • true: the payment method is available and may become a successful payment.
  • false: The payment method is unavailable. Do not allow users to select this payment method.

unavailable_reason

string
Reason of unavailable payment method. E.g. Insufficient wallet balance.

This can be displayed on the merchant's frontend as needed. If the payment method is available, this field will be hidden.

loan_tenure

intRequired
The number of months during which the installment is to be paid.

For example, if it's a 6-month installment, this value is 6.

monthly_payment

intRequired
Total monthly payments to be paid by the user.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

payment_promo_info

object
Applicable promotion for the transaction.

There can be one of more promotion applicable for a single transaction.
Show child child parameters

applicability

stringRequired
Indicates the scope under which the promotion is applicable.

Possible values:

  • global: The promotion is applicable to all payment methods.
  • payment_method: The promotion is specific to this payment method.

promo_type

stringRequired
Type of the applicable promotion. Refer to Promotion Type V2.

promo_text

stringRequired
Promotional text to be shown to users on merchant's frontend.

savings_amount

int
The amount that the user can save with this applied promotion.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

Conditional: This is returned when promo_type = DISCOUNT or COIN_REDEMPTION.

fee_amount_after_waived

int
The after-waiver transaction fee.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

Conditional: This is returned when promo_type = FEE_WAIVER.

transaction_fee

int
ShopeePay transaction fees that are charged to users based on payment methods.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

This parameter is to inform users of any fees that might apply beyond the main order amount, which must be displayed on the merchant's frontend for user's awareness before selection.

Note: Merchant should NOT need to adjust the order amount during the Direct Payment API request. Transaction fees are calculated and applied automatically by our system.

payable_amount

intRequired
Total amount that user should pay, given a specific payment method, considering promotions (if any) and fees (if any).

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

payment_promo_info

object
Applicable promotion for the transaction.

There can be one of more promotion applicable for a single transaction.
Show child child parameters

applicability

stringRequired
Indicates the scope under which the promotion is applicable.

Possible values:

  • global: The promotion is applicable to all payment methods.
  • payment_method: The promotion is specific to this payment method.

promo_type

stringRequired
Type of the applicable promotion. Refer to Promotion Type V2.

promo_text

stringRequired
Promotional text to be shown to users on merchant's frontend.

savings_amount

int
The amount that the user can save with this applied promotion.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

Conditional: This is returned when promo_type = DISCOUNT or COIN_REDEMPTION.

fee_amount_after_waived

int
The after-waiver transaction fee.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

Conditional: This is returned when promo_type = FEE_WAIVER.

transaction_fee

int
ShopeePay transaction fees that are charged to users based on payment methods.

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

This parameter is to inform users of any fees that might apply beyond the main order amount, which must be displayed on the merchant's frontend for user's awareness before selection.

Note: Merchant should NOT need to adjust the order amount during the Direct Payment API request. Transaction fees are calculated and applied automatically by our system.

payable_amount

intRequired
Total amount that user should pay, given a specific payment method, considering promotions (if any) and fees (if any).

This parameter is inflated by 100: the smallest value is 1, which represents 0.01, while for currencies that don't support cents, the smallest value is 100, which represents 1.

Sample API Response



{
  "request_id": "123",
  "errcode": 0,
  "debug_msg": "success",
  "saved_payment_methods": [
    {
      "payment_method_type": "ewallet",
      "saved_payment_method_id": "1042e4cee8ebd77de",
      "payment_option_reference": "9A2S3CdWkp8n6Q2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8",
      "display_name": "ShopeePay Wallet",
      "description": "Fast, secure, and widely accepted. Pay instantly using Wallet",
      "icon_url": "https://proxy.uss.s3.test.shopee.io/api/v4/0018404/shopee_logo_test_bucket/static/images/Img_giro_acbank.png",
      "payment_method_availability": {
        "is_available": true
      },
      "payment_method_details": {
        "ewallet": {
          "available_balance": "500000"
        }
      },
      "payment_promo_info": [
        {
            "applicability": "global",
            "promo_type": "COINS_REDEMPTION",
            "promo_text": "- Rp1000 from ShopeePay Coins redemption",
            "savings_amount": "100000"
          },
          {
            "applicability": "payment_method",
            "promo_type": "DISCOUNT",
            "promo_text": "- Rp1000",
            "savings_amount": "100000"
          },
          {
            "applicability": "payment_method",
            "promo_type": "CASHBACK",
            "promo_text": "+Rp1000 Bonus"
          },
          {
            "applicability": "payment_method",
            "promo_type": "COINBACK",
            "promo_text": "+100 Coins"
          }
      ],
      "transaction_fee": "20000",
      "payable_amount": "620000"
    },
    {
      "payment_method_type": "spay_later",
      "display_name": "SPayLater",
      "description": "Buy Now Pay Later with 0% interest",
      "icon_url": "https://proxy.uss.s3.test.shopee.io/api/v4/0018404/shopee_logo_test_bucket/static/images/ic_paymentoption_wallet_v2.png",
      "payment_method_details": {
        "spay_later": {
          "credit_balance": "300000000",
          "compliance_notices": [
              {
                "content": [
                  {
                    "content_type": "text",
                    "text": "I agree to the SPayLater”,
                    "bold": false
                  },
                  {
                    "content_type": "link",
                    "text": "Loan agreement",
                    "url": "https://spl_tnc.com/loan_agreement,
                    "bold": true
                  }
                ]
              },
              {
                "content": [
                  {
                    "content_type": "link",
                    "text": “Transaction Notice”,
                    "url": "https://txnnotice.com/notice",
                    "bold": true
                  }
                ]
              }
          ],
        }
      },
      "spaylater_options": [
        {
          "saved_payment_method_id": "1042e4cee8ebd77de",
          "payment_option_reference": "9A7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoDkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD",
          "display_name": "3-Month Installments",
          "payment_method_availability": {
          "is_available": true
                },
          "loan_tenure": 3,
          "monthly_payment": 1600000,
          "payment_promo_info": [
                  {
                    "applicability": "global",
                    "promo_type": "COINS_REDEMPTION",
                    "promo_text": "- Rp1000 from ShopeePay Coins redemption",
                    "savings_amount": "700000"
                  },
                  {
                    "applicability": "payment_method",
                    "promo_type": "INTEREST_WAIVER",
                    "promo_text": "0% Interest"
                  }
                ],
          "transaction_fee": "20000",
          "payable_amount": "620000"
        },
        {
          "saved_payment_method_id": "3542e4cee8ebd672f",
          "payment_option_reference": "4AsHL7OmCyQ2S3C9AsHL9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHn62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD7OmCyQ2S3CdWkp8n62GcXsqkq84ZoDdWkp8n62GcXsqk344DH2",
          "display_name": "12-Month Installments",
          "payment_method_availability": {
             "is_available": true
           },
          "loan_tenure": 12,
          "monthly_payment": 1200000,
          "payment_promo_info": [
                  {
                    "applicability": "global",
                    "promo_type": "COINS_REDEMPTION",
                    "promo_text": "- Rp1000 from ShopeePay Coins redemption",
                    "savings_amount": "100000"
                  },
                  {
                    "applicability": "payment_method",
                    "promo_type": "INTEREST_WAIVER",
                    "promo_text": "0% Interest"
                  }
                ],
          "transaction_fee": "20000",
          "payable_amount": "620000"
        }
      ]
    },
    {
      "payment_method_type": "giro_bank",
      "saved_payment_method_id": "1042e4cee8ebd77de",
      "payment_option_reference": "9AsHL7OmCyQ2S3CdWkp8n62G9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq849AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoDcXsqkq84ZoD",
      "display_name": "SeaBank",
      "icon_url": "https://proxy.uss.s3.test.shopee.io/api/v4/0018404/shopee_logo_test_bucket/static/images/Img_giro_acbank.png",
      "payment_method_availability": {
        "is_available": true
      },
      "payment_method_details": {
        "giro_bank": {
          "last_4digits": "5536"
        }
      },
      "payment_promo_info": [
          {
            "applicability": "global",
            "promo_type": "COINS_REDEMPTION",
            "promo_text": "- Rp1000 from ShopeePay Coins redemption",
            "savings_amount": "100000"
          },
          {
            "applicability": "payment_method",
            "promo_type": "FEE_WAIVER",
            "promo_text": "Free Admin Fee",
            "feeAmountAfterWaived": "100000"
          },
          {
            "applicability": "payment_method",
            "promo_type": "REWARD",
            "promo_text": "A Lucky Draw"
          }
        ],
      "transaction_fee": "20000",
      "payable_amount": "620000"
    },
    {
      "payment_method_type": "card",
      "saved_payment_method_id": "1042e4cee8ebd77de",
      "payment_option_reference": "9AsHL7OmCyQ284ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoD9AsHL7OmCyQ2S3CdWkp8n62GcXsqkq84ZoDkp8n62GcXsqkq84ZoD",
      "display_name": "HSBC",
      "icon_url": "https://proxy.uss.s3.test.shopee.io/api/v4/0018404/shopee_logo_test_bucket/static/images/Img_giro_acbank.png",
      "payment_method_availability": {
        "is_available": false,
        "unavailable_reason": "The card has expired"
      },
      "payment_method_details": {
        "card": {
          "last_4digits": "5536",
          "card_type": "credit_card",
          "network": "visa"
        }
      },
      "transaction_fee": "20000",
      "payable_amount": "620000"
    }
  ]
}
arrow-svg

Copy

Direct Payment

Use this endpoint to create a payment with an access token. If the user has selected a certain payment method on the merchant's checkout page, the payment_method_type and the payment_option_reference should be provided as the user's choice of method.

  • URL: "/v3/merchant-host/transaction/payment/direct"

Request Parameters

request_id

stringRequired
Unique identifier of the API request.

access_token

stringRequired
The access token that was obtained from ShopeePay via the Get Access Token API, representing the user's authorization.

merchant_ext_id

stringRequired
Unique identifier of the merchant in the merchant's system.

store_ext_id

stringRequired
Unique identifier of the store in the merchant's system.

amount

int64
The order amount. If this parameter is provided, we will precheck the availability of each payment method using this amount.

Note that the value of this parameter is inflated by 100. For example, if the currency is SGD and the amount is $12.34, set the value of this parameter to 1234. If the currency is VND and the amount is 123, set the value of this parameter to 12300.

language

string
Language in which the linked payment methods are displayed. The default is English.

Possible values:

  • Indonesian : id
  • English: en
  • Malay: ms
  • Thai: th
  • Vietnamese:vi

additional_info

object
Show child child parameters

field1

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field2

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

field3

String
Any Payment Remark for ShopeePay Clearing Order Report. This can be a customized value for reconciliation purpose.

device_info

Object
Show child child parameters

device_id

String
Merchant's unique identifier for the user's device.

device_brand

String
Brand of the device, e.g. 'Apple', 'Samsung'.

device_model

String
Model of the device, e.g. 'iPhone 14', 'Galaxy S24'.

os_version

String
Operating system and version, for example: 'iOS 16', 'Android 14'.

iosudid

String
Unique device identifier for iOS devices.

imei

String
Unique identifier such as IMEI (for compatible devices).

verification_completion_method

String
Verification that happens within merchant app.

Potential enum:

  • none
  • biometric
  • pin
  • password
  • pattern
  • other

device_first_login_at

String
Earliest timestamp when this device first logged in to the merchant app.

risk_tags

Object
Show child child parameters

jailbroken

Boolean
true if jailbroken (iOS) or rooted (Android)

enabled_emulator

Boolean
true if the app is running in an emulator environment (for example Genymotion).

enabled_remote_control

Boolean
true if remote access / remote control tools (for example TeamViewer, scrcpy) are active

modified_gps

Boolean
true if GPS appears tampered or inconsistent (possible GPS modification).

installed_fake_gps_app

Boolean
true if known fake-GPS apps are installed on the device.

gps

Object
Show child child parameters

latitude

Float
Device latitude at the time of transaction.

longitude

Float
Device longitude at the time of transaction.

location

String
Human-readable GPS location, for example: country and city. IP address of the device at the time of transaction.

device_ip

String
IP address of the device at the time of transaction.

device_risk_score

String
Risk score assigned by merchant’s system.
Potential enum values: high, medium, low.

additional_info

String
Any extra device-related risk information not covered by the structured fields.

user_account

Object
Show child child parameters

user_id

String
Identifier that uniquely represents the user in the merchant’s system.

phone_number

String
At least one of phone_number, email, or username must be provided.

email

String
At least one of phone_number, email, or username must be provided.

username

String
At least one of phone_number, email, or username must be provided.

account_registration_time

String
Timestamp when the user account was first registered with the merchant.

account_risk_score

String
Risk score assigned to the user account by the merchant.
Potential enum values: high, medium, low.

merchant_account

Object
Show child child parameters

merchant_name

String
Merchant business name

merchant_id

String
Identifier for each unique merchant onboarded by payment facilitator (most aggregated level)

merchant_mcc

String
Merchant Category Code (MCC). Leave blank if the external merchant differentiates only by store level.

merchant_address

Object
Show child child parameters

region

String
Registered address of the merchant. Leave blank if you only differentiate at store/outlet level.

state

String

city

String

address

String

postal_code

String

store

Object
Show child child parameters

store_name

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_id

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_mcc

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

store_address

Object
Show child child parameters

region

String
If external merchant differentiates by store / outlet, to get store / outlet info.
otherwise leave blank.

state

String

city

String

address

String

postal_code

String

order_details

Object
Show child child parameters

payment_initiation

String
Indicates how the payment is initiated.

Potential value:

  • MERCHANT_QR_PROPRIETARY: Merchant-presented proprietary QR scanned by the customer to initiate payment.
  • MERCHANT_QR_NATIONAL: Merchant-presented national / standardized QR scanned by the customer to initiate payment.
  • CUSTOMER_QR_PROPRIETARY: Customer-presented proprietary QR scanned by the merchant to initiate payment.
  • CUSTOMER_QR_NATIONAL: Customer-presented national / standardized QR scanned by the merchant to initiate payment.
  • ONLINE_CHECKOUT: Online checkout where the customer confirms an order and pays with a non-QR method (card, wallet, giro, etc.).
  • SUBSCRIPTION: Recurring or scheduled billing initiated automatically
  • TRANSFER: Fund transfer between accounts (for example, P2P or internal balance movement) without an order/cart.

description

String
Free-text description of the charge.

shipping_address

Object
Show child child parameters

region

String
Shipping address where goods are delivered. Mandatory for online merchants except for purely virtual goods.

state

String

city

String

address

String

postal_code

String

merchant_additional_info

String
Additional merchant-specific information for this order, if any.

items

Object
Show child child parameters

item_name

String
item name user bought in online platform or App.

item_quantity

Int
item number user bought in online platform or App.

item_currency

String
item currency Example, SGD.

item_amount

Int64
item amount

item_category

String
Category of the item (merchant-defined taxonomy).

qr_details

Object
Show child child parameters

qr_type

String
Potential values: 'static' or 'dynamic'.

qr_create_time

String
Creation timestamp for dynamic QR codes.

qr_source

String
How the user submitted the QR for payment.

Potential values: 'scan'; 'upload'

national_qr_payload

String
Raw national QR payload string as defined by the national QR standard.

Sample API Request

{
        "request_id": "input-unique-request-id-here",
        "payment_reference_id":"ref-must-be-unique",
        "merchant_ext_id": "external-merchant",
        "store_ext_id":"external-store",
        "access_token": "uXjWuhPGepSOtntoC8kTK5er6DlbUiGeSJDt53",
        "amount":  1000000,
        "currency": "IDR",
        "use_coin": true,
        "return_url": "https://isv-domain.com",
        "expiry_time": 1716193900
}
arrow-svg

Copy

Response Parameters (When Payment Verification is Required)

request_id

stringRequired
The same value as the request_id in the request.

errcode

stringRequired
Error code to specify the error returned.

debug_msg

stringRequired
Debug message to provide more information.

redirect_url

stringRequired
The URL for the merchant’s FE to redirect the user to ShopeePay’s page. Note: This field will be returned when there's payment confirmation or verification required. If this is returned, the final state of the transaction will be informed via the Notify Transaction Status API. Otherwise, the state of the transaction will be reflected in the Direct Payment API response.

Sample API Response (When Payment Verification is Required)

{
        "request_id": "input-unique-request-id-here",
        "errcode": 0,
        "debug_msg": "success",
        "redirect_url": "https://uat.shopeepay.co.id/s/browser/payment/auth/passcode-verify?mode=fullscreen&next=https%3A%2F%2Fuat.shopee.vn%2Fs%2Fbrowser%2Fpayment%2Fauth%2FtokenizedPaymentResult%3Freturn_url%3Dhttps%253A%252F%252Fgoogle.com%26ticket%3DbxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM&return_url=https%3A%2F%2Fuat.shopee.vn%2Fs%2Fbrowser%2Fpayment%2Fauth%2FtokenizedPaymentResult%3Fresult%3D201%26return_url%3Dhttps%253A%252F%252Fgoogle.com%26ticket%3DbxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM&scenario=7cdccb66-cd7a-448f-a01f-b2ddd8970e53&source=TokenizedPayment&ticket=bxfWQkI0VfGzlj7ANMudkMYO9RvkO1PM"
}
arrow-svg

Copy

Response Parameters (When Payment Verification is Not Required)

request_id

stringRequired
The same value as the request_id in the request.

errcode

int32Required
Error code to specify the error returned.

debug_msg

stringRequired
Debug message to provide more information.

transaction

objectRequired
Will not be returned if the transaction fails.
Show child child parameters

reference_id

stringRequired
Unique identifier of payment transaction generated by merchant. Same value as the payment_reference_id in the request.

amount

int64Required
Amount used for the payment, inflated by a factor of 100. A positive integer in the smallest currency unit, with no decimal point. Example: Smallest amount will be 1, which represents 0.01. For currencies that do not have denomination in cents, the smallest amount will be 100, which represents 1 IDR (Rp 1) or 1 VND (₫ 1).

status

uint32Required
Refer to Transaction Status for specific transaction statuses.

transaction_type

uint32Required
13, referring to subscription transaction type. Refer to Transaction Types for specific transaction types.

transaction_sn

stringRequired
Transaction identifier in ShopeePay's system.

create_time

uint32Required
Create time of the transaction.

update_time

uint32Required
Update time of the transaction.

user_id_hash

stringRequired
Identifier for the customer that made the payment.

merchant_ext_id

uint32Required
Unique identifier of merchant in merchant's system.

store_ext_id

stringRequired
Unique identifier of store in merchant's system.

promo_id_applied

stringRequired
promo_ids applied to the payment transaction.

payment_channel

uint32Required
Indicates the source of funds used. Refer to Payment Channels for the respective source of fund.

payment_method_type

stringRequired
Indicates payment method that being used for payment (eg. ewallet/ giro_bank/card). Refer to payment_method_type.

Sample API Response (When Payment Verification is Not Required)

JS EXAMPLE

{
            "request_id": "input-unique-request-id-here",
            "errcode": 0,
            "debug_msg": "success",
            "transaction": {
                  "reference_id": "input-payment-ref-id",
                  "amount": 1000000,
                  "create_time": 1716193693,
                  "update_time": 1716193693,
                  "transaction_sn": "4737856404311306",
                  "status": 3,
                  "transaction_type": 13,
                  "merchant_ext_id": "external-merchant",
                  "store_ext_id": "external-store",
                  "user_id_hash": "697863f9295aeddcb3db598ecbc74c59a13335abf4d8c41b40e33b28a9d7d63c",
                  "payment_channel": 1,
                  "payment_method_type": "ewallet"
            }
}
arrow-svg

Copy

Response Code

ValueDescription
-2A server dropped the connection
-1A server error occurred
0Success
1The request parameters is invalid or a mandatory parameter is empty
2Permission denied, often due to invalid status
4Not found, often due to merchant/store/user/transaction not found
9Customer’s account is banned
11Duplicated request
14Customer’s account is deleted
24Customer's account is frozen
27Customer's account is not activated
42Insufficient balance
43Insufficient balance
50The request parameters is invalid due to payload sent is not a valid JSON
105Invalid auth code
140Customer’s wallet limit is reached
1001Customer is not allowed to make the transaction
1100ShopeePay internal payment module error
1101ShopeePay internal payment module error
1102Customer’s SPL credit limit is reached
1103Customer is required to link their bank account
1104Ineligible payment channel
1105Transaction failed due to unsuccessful authentication
1106Duplicated payment
1200ShopeePay internal payment module error
1201ShopeePay internal payment module error
1500ShopeePay internal payment module error
1800ShopeePay internal payment module error
1801ShopeePay internal payment module error
1906Unable to process refund due to transaction has been failed
1907Ineligible payment channel
1908Service is temporarily down for scheduled maintenance
300088Customer is required to complete verification
300210ShopeePay scam warning error message

On this page