Link user (1.0)


To be able to collect payment from PayPay user’s wallet, you need to obtain user’s authorization explicitly.

Acquiring user authorization is achieved through a simple web redirect flow, similar with OAuth/OpenID Connect style WebView authentication & authorization flow.

Upon successful authorization, a user authorization id will be issued to you per user. You should store this id in your backend and link it to your internal user. Please ensure this user authorization id is not stored on the client side. This id will be used as the user identifier in the Payment, Cashback and Topup requests. Authorization is valid for 365 days. It will be automatically extended each time you make a payment, grant a balance or re-authorize.

Onboard merchant

To start utilizing our Open Payment API platform, at first the business needs to be onboarded as a PayPay merchant.

This process usually consists of information collection, manual verification, contract confirmation and credentials issuance.

After becoming a merchant on PayPay, the following items would be setup for the client:

  • api key and secret
  • webhook endpoints
  • client IP whitelist

This setup can be managed using our merchant panel/ getting in touch with the sales representative.

Access from users to the PayPay app and PayPay web screen from outside Japan is restricted. Please contact us for details.

Acquiring user authorization

Direct user to the authorization web page

To acquire user's authorization, the host app should direct user to the PayPay authorization web page along with the parameters apiKey and a requestToken. In this page, user is able to login to PayPay and grant the direct debit permission to merchant or scan the QR code with PayPay application and link to the merchant.

Authorization page URL:Production server{apiKey}&requestToken={jwtToken}'

Authorization page URL:Sandbox server{apiKey}&requestToken={jwtToken}'

Required parameters

  • apiKey is the api key issued during the onboarding process

  • requestToken is a JWT token signed with the corresponding api key secret

  "alg": "HS256",
  "aud" : "",
  "iss" : "<merchant organization id>",
  "exp": 12456,
  "scope" : "direct_debit,get_balance",
  "nonce" : "<random case sensitive string>",
  "redirectUrl": "https://<merchant service auth redirect endpoint>",
  "referenceId": "<merchant user reference id>",
  "deviceId": ""
  base64UrlEncode(header) + "." +
  base64Decode(API SECRET)
cliam type description
aud string ""
iss string the merchant name
exp number The expiration date of the authorization page URL. Set with epoch time stamp (seconds).
scope array of string Scopes of the user authorization. Please select only what you need.
direct_debit:Native Payment
preauth_capture_native:Native Payment(Block and take money)
get_balance:Get balance
continuous_payments:Continuous payment
pending_payments:Request Money
merchant_topup:Transfer money to user balance
Transfer money to user balance

The following is only available at some special merchants.
nonce string will be sent back with response for the client side validation
redirectUrl url string The callback endpoint provided by client. Must be HTTPS, and its domain should be in the allowed authorization callback domains
referenceId string The id used to identify the user in merchant system. It will be stored in the PayPay db for reconsilliation purpose
deviceId string (Optional) The user mobile phone device id. If it is provided, we can use it to verify the user and skip the SMS verification, so as to provide more fluent UX

Receive the user authorization result

On PayPay's authorization page the user can choose to accept/ decline giving the merchant the authorization. Depending on the user action, the request to acquire user authorization could succeed or fail. We will encode the result into the JWT token and pass it back to the redirect url provided in the requestToken mentioned earlier. The specific parameters we will pass to the redirct url are as follows:

  • apiKey is the api key issued during the onboarding process

  • responseToken is a JWT token signed with the corresponding api key secret

    "typ": "JWT",
    "alg": "HS256",
    "aud" : "<merchant organization id>",
    "iss" : "",
    "exp" : 23567,
    "result": "succeeded",
    "profileIdentifier": "*******5678",
    "nonce" : "<the same nonce in the request>",
    "userAuthorizationId" : "<PayPay user reference id>",
    "referenceId": "<merchant user reference id>"
claim type description
aud string the merchant name
iss string ""
exp number The expiration date of the authorization page URL. Set with epoch time stamp (seconds).
result string succeeded, declined or bad_request
profileIdentifier string Masked phone number or email e.g. "*******5678", "abc*******"
nonce string the same nonce in the request for client side to validate the response
userAuthorizationId string PayPay user reference id which you should store in your db and use it in the api calls. Max length 64 chars
referenceId string the same referenceId in the request

So, after the user accepted or declined the authorization request, we will redirect the webview to the following URL.

https://<redirect url>?apiKey={apiKey}&responseToken={jwtToken}