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.

merchant_device_info

json string
Show child child parameters

device_identifier_info

Show child child parameters

device_id

Required
Merchant-generated unique identifier for the user’s device (not an OS-level identifier).

iosudid

Unique device identifier for iOS devices.

imei

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

os_version

Operating system and version, for example: “iOS 16”, “Android 14”.

brand

Brand of the device, for example: “Apple”, “Samsung”

model

Model of the device, for example: “iPhone 14”, “Galaxy S24”.

risk_tags

Show child child parameters

is_jailbreak

Boolean. true if the device is jailbroken (iOS) or rooted (Android)

is_emulator

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

is_remote_control_enabled

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

is_gps_modified

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

has_fake_gps_app_installed

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

location_info

Show child child parameters

latitude

Device latitude at the time of transaction.

longitude

Device longitude at the time of transaction.

location

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

device_behavior_info

Show child child parameters

verification_completion_method

Verification method used within the merchant app to complete the current session or transaction.
Potential enum:

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

device_first_login_timestamp

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

device_risk_score

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

network_risk_info

Show child child parameters

device_ip

IP address of the device at the time of transaction.

additional_info

Additional merchant-specific information relates to device info, if any.

merchant_user_account_info

json string
Show child child parameters

user_identifier_info

Show child child parameters

user_id

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

phone_number

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

email

username

account_time_info

Show child child parameters

account_registration_time

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

account_risk_info

Show child child parameters

account_risk_score

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

customized_partner_merchant_info

json string
Show child child parameters

merchant_basic_info

Show child child parameters

merchant_name

Required
Merchant’s business name.

merchant_id

Required
identifier for each unique merchant onboarded by payment facilitator (most aggregated level)

merchant_mcc

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

merchant_address

Show child child parameters

region

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

state

city

address

postal_code

store_basic_info

Show child child parameters

store_name

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

store_id

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

store_mcc

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

store_address

Show child child parameters

region

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

state

city

address

postal_code

order_detail

json string
Show child child parameters

shipping_address

Show child child parameters

region

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

state

city

address

postal_code

item_info

Show child child parameters

name

item name user bought in online platform or App

quantity

item number user bought in online platform or App

currency

item currency Example, SGD

amount

item amount

category

Category of the item (merchant-defined taxonomy).

additional_info

Additional merchant-specific information relates to order, if any.

description

Free-text description of the charge.

qr_details

Show child child parameters

qr_type

Required
Potential values: 'static' or 'dynamic'

qr_source

Required
How the user submitted the QR for payment.\nPotential values: 'scan'; 'upload'

national_qr_payload

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

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.

The following scenarios define which risk field the merchant should provide to SPP:

Payment Initiation ScenarioDescriptionAPI Fields
SETTLEMENTfield1, field2, field3
MERCHANT_QR_PROPRIETARYMerchant-presented proprietary QR scanned by the customer to initiate payment.Device Info, User Account, Merchant Account, Order Details
MERCHANT_QR_NATIONALMerchant-presented national QR scanned by the customer to initiate payment.Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading)
CUSTOMER_QR_PROPRIETARYCustomer-presented proprietary QR scanned by the merchant to initiate payment.Device Info, User Account, Merchant Account, Order Details
CUSTOMER_QR_NATIONALCustomer-presented national / standardized QR scanned by the merchant to initiate payment.Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading)
ONLINE_CHECKOUTOnline checkout where the customer confirms an order and pays the non-QR method transaction.Device Info, User Account, Merchant Account, Order Details, Items

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

int64Required
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.

currency

stringRequired
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.

return_url

string
Indicates the URL of the Client’s platform to redirect back to, once payment verification on ShopeePay is completed.

Note: This field is mandatory only for 'Link\&Pay(Redirection)' and 'Link\&Pay(API-Based)' product flow.

payment_method_type

string
Type of payment method used. This value identifies the category of the payment method. Refer to payment_method_type section for specific payment method type. This field is mandatory only for 'Link and Pay(API-Based)' product flow.

payment_option_reference

string
A unique identifier that generated from Get Payment Methods API. This field is mandatory only for 'Link and Pay(API-Based)' product flow.

expiry_time

uint32
Unix timestamp indicating when the order will expire.
By default, the expiry time will be set as 30 minutes (1800 seconds), from the time the request was received.

If provided, the timestamp must be no more than 30 minutes (1800 seconds) after the request time. 
After this time, payment attempts for the corresponding payment_reference_id will fail.

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.

merchant_device_info

Show child child parameters

device_identifier_info

Show child child parameters

device_id

json string
Merchant-generated unique identifier for the user’s device (not an OS-level identifier).

iosudid

Unique device identifier for iOS devices.

imei

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

os_version

Operating system and version, for example: “iOS 16”, “Android 14”.

brand

Brand of the device, for example: “Apple”, “Samsung”

model

Model of the device, for example: “iPhone 14”, “Galaxy S24”.

risk_tags

Show child child parameters

is_jailbreak

Boolean. true if the device is jailbroken (iOS) or rooted (Android)

is_emulator

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

is_remote_control_enabled

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

is_gps_modified

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

has_fake_gps_app_installed

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

location_info

Show child child parameters

latitude

Device latitude at the time of transaction.

longitude

Device longitude at the time of transaction.

location

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

device_behavior_info

Show child child parameters

verification_completion_method

Verification method used within the merchant app to complete the current session or transaction.
Potential enum:

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

device_first_login_timestamp

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

device_risk_score

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

network_risk_info

Show child child parameters

device_ip

IP address of the device at the time of transaction.

additional_info

Additional merchant-specific information relates to device info, if any.

merchant_user_account_info

Show child child parameters

user_identifier_info

Show child child parameters

user_id

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

phone_number

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

email

username

account_time_info

Show child child parameters

account_registration_time

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

account_risk_info

Show child child parameters

account_risk_score

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

customized_partner_merchant_info

Show child child parameters

merchant_basic_info

Show child child parameters

merchant_name

json string
Merchant’s business name.

merchant_id

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

merchant_mcc

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

merchant_address

Show child child parameters

region

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

state

city

address

postal_code

store_basic_info

Show child child parameters

store_name

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

store_id

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

store_mcc

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

store_address

Show child child parameters

region

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

state

city

address

postal_code

order_detail

Show child child parameters

shipping_address

Show child child parameters

region

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

state

city

address

postal_code

item_info

Show child child parameters

name

item name user bought in online platform or App

quantity

item number user bought in online platform or App

currency

item currency Example, SGD

amount

item amount

category

Category of the item (merchant-defined taxonomy).

additional_info

Additional merchant-specific information relates to order, if any.

description

Free-text description of the charge.

qr_details

Show child child parameters

qr_type

Potential values: 'static' or 'dynamic'

qr_source

How the user submitted the QR for payment.\nPotential values: 'scan'; 'upload'

national_qr_payload

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

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.

The following scenarios define which risk field the merchant should provide to SPP:

Payment Initiation ScenarioDescriptionAPI Fields
SETTLEMENTfield1, field2, field3
MERCHANT_QR_PROPRIETARYMerchant-presented proprietary QR scanned by the customer to initiate payment.Device Info, User Account, Merchant Account, Order Details
MERCHANT_QR_NATIONALMerchant-presented national QR scanned by the customer to initiate payment.Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading)
CUSTOMER_QR_PROPRIETARYCustomer-presented proprietary QR scanned by the merchant to initiate payment.Device Info, User Account, Merchant Account, Order Details
CUSTOMER_QR_NATIONALCustomer-presented national / standardized QR scanned by the merchant to initiate payment.Device Info, User Account, Merchant Account, Order Details, QR Details (If Merchant who handles QR reading)
ONLINE_CHECKOUTOnline checkout where the customer confirms an order and pays the non-QR method transaction.Device Info, User Account, Merchant Account, Order Details, Items

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