Launched in 2018, PayPay has emerged as the leading mobile payment app in Japan, boasting a user base of over 65 million. The app's success can be attributed to its strategic marketing campaigns, user-friendly payment experience, diverse range of services, and seamless integration across online and offline platforms. Since its inception, PayPay has effectively steered local consumers away from traditional cash transactions towards the convenience of digital payments, making it an indispensable tool in the daily lives of Japanese individuals.

PayPay is integrated with bank accounts, credit cards, and debit cards, simplifying the process of topping up the PayPay wallet. Whether making online or in-store purchases, buyers can effortlessly complete transactions by scanning QR codes, barcodes, or entering the account information. With widespread acceptance throughout Japan, PayPay boasts a payment ratio exceeding 45%, surpassing other prominent digital wallets in the country.

Payment Method Properties

Make an PayPay Payment

One-time PayPay payments follow our standard redirect payment flow, so you can add PayPay to your integration in seconds.

To make an PayPay payment, you'll need to provide the following data at minimum when calling our /v1/payment-charges API:

Request

POST /v1/payment-charges

{
    "paymentDescriptor": "Order Description",
    "order": {
        "orderReferenceNumber": "23423423"
    }
    "paymentMethod": "PAYPAY",
    "amount": {
        "value": 1000,
        "currency": "JPY"
    },
    "consumer": {
        "name": "Jim Sim",
        "country": "JP"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.your-merchant-success-page.com/"
            }
        }
    ],
    "merchantPaymentChargeReference": "YOURPAYMENTREFERENCEHERE",
}

Response

You'll receive one of our standard payment charge responses (see potential responses in the API Reference)

{
  "id": "charge_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  
  // ...
  
  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://redirection-target.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Consumer Authentication

PayPay requires a consumer authentication step before the payment is authorized and captured.

In your response to your charge creation request, you will receive the authenticationMethods list with an authentication method of standard type REDIRECT

Redirect the consumer to the page url specified in the requestUrl field. The consumer will be taken to PayPay's pages to log in to their account and approve the payment.

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer confirms the payment in their app. After this, the charge will transition to the CAPTURED state.

Handling the Payment Result

The consumer will be redirected to the authenticationMethods.settings.returnUrl provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.

Recurring Payments

PayPay offers recurring payment support - we simplify this flow for you with our Payment Agreements API.

Create the Payment Agreement

To set up a recurring agreement for PayPay, you'll need to provide at minimum the following data when calling our /v1/payment-agreements API:

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

• The exact amount.value and amount.currency of the first payment

Request

{
    "paymentMethod": "PAYPAY",
    "startDate": "2023-03-26T20:24:27Z",
    "consumer": {
        "name": "Jim Sim",
        "country": "JP"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.your-merchant-success-page.com/"
            }
        }
    ],
    "initialPaymentCharge": {
        "paymentDescriptor": "Order Description",
        "amount": {
            "value": 1000,
            "currency": "JPY",
            "merchantPaymentChargeReference": "YOURREFERENCEHERE"
        },
        "order": {
            "orderReferenceNumber": "42342342423423"
        }
    }
}

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Response

You'll receive one of our standard payment agreement responses (see responses in the API Reference)

{
  "id": "agrmt_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  "startDate": "2023-03-26T20:24:27Z",
  "initialPaymentChargeId": "charge_X0O78tadFHrZCasfhkycPk",

  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://some-redirection-page.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Redirect the consumer to url specified in requestUrl. The consumer will be taken to PayPay to log into their account and approve the payment agreement.

Once the consumer has confirmed the recurring agreement creation, the agreement status will transition to ACTIVE, and subsequent payments can be made without consumer interaction.

Make Subsequent Recurring Charges

Once you've set up a payment agreement, it's simple to create subsequent charges against it. In your /v1/payment-agreements/{agreement-id}/payment-charges/ request, you just need to include:

{  
    "amount": {  
        "amount": 9000,  
        "currency": "JPY"  
    }, 
    "paymentDescriptor": "Order Description",
    "order":{
         "orderReferenceNumber": "42342342423423"
    },
    "merchantPaymentChargeReference": "external-identifier", //optional  
		"autoCapture": true  
}

You will receive webhooks for all charges created under a Payment Agreement the same way you would for individual charges, and can respond accordingly.