PayPay Open Payment Api
API docs by Redocly

Get balance (1.0)

Introduction

Get balance provides a service that allows users to get balance in each account and the total balance in the wallet.

TLS implementation

The PayPay Open Payment API requires that you use TLS 1.2 or higher as a security measure. Note that you cannot connect with TLS1.0 and TLS1.1.

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.

Acquire user authorization

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

Acquiring user authorization can be achieved using our simple account linking flow here.

OPA API Authorization

Everything related to OPA API Authorization is described here.

Error Handling

PayPay OPA uses HTTP response status codes and OPA error code to indicate the success or

failure of the requests. With these information, you can decide what error handling strategy

to use. In general, PayPay OPA return the following http status codes.

Response code list

Common response code

Status Code Description
200 SUCCESS Success
400 INVALID_REQUEST_PARAMS The information provided by the request contains invalid data, e.g., unsupported push text.
400 BAD_REQUEST Other cases that we do not mention.
400 MISSING_REQUEST_PARAMS The request does not contain required data.
401 UNAUTHORIZED No valid api key and secret provided
401 INVALID_USER_AUTHORIZATION_ID The specified user authorization ID is invalid.
401 OP_OUT_OF_SCOPE The operation is not permitted.
404 OPA_CLIENT_NOT_FOUND OPA Client not found
429 RATE_LIMIT Too many requests
500 INTERNAL_SERVER_ERROR Something went wrong on PayPay service side.
500 SERVICE_ERROR A service error has occurred.
503 MAINTENANCE_MODE Sorry, we are in maintenance.

Wallet

Everything related to user wallet balance

Get user wallet balance

Retrieve the total amount in a user's Wallet. Application to PayPay is separately required to get user wallet balance. Timeout: 15s

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

currency
required
string
Value: "JPY"
productType
string (ProductTypeForGetBalanceMixin)
Enum: "VIRTUAL_BONUS_INVESTMENT" "PAY_LATER_REPAYMENT" "REAL_INVESTMENT" "POINT"

The product type in PayPay system. Generally, this request parameter is optional. For some merchants that are restricted to use only certain product types, the product type must be properly set.
When merchant passes productType either VIRTUAL_BONUS_INVESTMENT or POINT, PayPay returns the user's current point balance regardless of the setting status of useCashback flag.

onetimeUseCashback
string (OnetimeUseCashbackForGetBalance)
Enum: "ENABLED" "DISABLED"
Example: onetimeUseCashback=ENABLED

To use this parameter, onetime_use_cashback scope is required.

Whether to include cashback. For example, PayPay will take cashback balance into account if it's "ENABLED". Likewise, PayPay will exclude cashback amount when it's "DISABLED".

Note: This parameter will be ignored when the master setting is "Earn Points"

If it is not provided, PayPay will apply user's master settings.

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

User

Get masked user profile

Get the masked phone number of the user

query Parameters
userAuthorizationId
required
string (UserAuthorizationId) <= 64 characters

The PayPay user reference id returned by the user authorization flow

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Changelog

Date of Documentation Update Date of Release Type of Change Section Updates
2023.01.12 2023.01.13 Feature Get user wallet balance When merchant passes productType either VIRTUAL_BONUS_INVESTMENT or POINT, PayPay returns the user's current point balance regardless of the setting status of useCashback flag.