Integrate Pay upon Invoice

DOCS

Last updated: Mar 3rd, 10:38am

Pay upon Invoice is a payment method in Europe.

Countries Payment type Currencies Minimum amount Maximum amount Refunds
Germany (DE) Deferred payment EUR 5 EUR 2,500 EUR Within 180 days

Know before you code

  • Make sure you're subscribed to the following webhook events:
    • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture. In the case of Pay Upon Invoice, this means that the order status changed from PENDING_APPROVAL to APPROVED.
    • The PAYMENT.CAPTURE.DENIED and CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook events indicate a failed order capture.
  • Make sure your preference for receiving payments in your PayPal business or merchant account is set to accept and convert to the currency in your account. In your profile, select Account Settings > Payment preferences > Block payments and click Update to mark this preference.
  • You can use only intent=CAPTURE in Create order to process payments using Pay upon Invoice.
  • Request that buyers provide their birth date to process payments using Pay upon Invoice.
  • You are legally obligated to display the messages to the buyer as described in Offer Pay upon Invoice on your checkout page 
  • Use Postman to explore and test PayPal APIs.

By clicking on the button, you agree to the terms of payment and performance of a risk check from the payment partner, Ratepay. You also agree to PayPal’s privacy statement privacy statement. If your request to purchase upon invoice is accepted, the purchase price claim will be assigned to Ratepay, and you may only pay Ratepay, not the merchant.

3. Use the API calls and webhooks described in the remainder of this topic to:

  • Create the order with Pay upon Invoice as the payment source.
  • Listen to webhooks to get the result of the order capture and fulfill the order.
1

Onboard your sellers

Onboard your sellers before payment so they can accept Pay upon Invoice as a payment method. You can also build onboarding into your software.

Follow the steps in this guide to onboard your sellers for Pay upon Invoice.

Partner Referrals API for Pay upon Invoice has a sample request and response specific to Pay upon Invoice.

Partner configuration

You must configure your account to enable Pay upon Invoice. Work with your account manager to configure the features you need.

Partner Referrals API for Pay upon Invoice

Call the Partner Referrals API to generate a sign-up link that redirects your sellers to sign up with PayPal. Passing your seller's information during the API call will pre-fill the PayPal sign-up flow with your seller's information.

Request sample

    1curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
    2 -H "Content-Type: application/json" \
    3 -H "Authorization: Bearer <Access-Token>" \
    4 -H "PayPal-Request-Id: 7b92603e-77ed-4896-8e78-5dea2050476a" \
    5 -d '{
    6 "business_entity": {
    7 "business_type": {
    8 "type": "PRIVATE_CORPORATION"
    9 },
    10 "addresses": [
    11 {
    12 "address_line_1": "Parkstr. 26",
    13 "admin_area_1": "Berlin",
    14 "postal_code": "13086",
    15 "country_code": "DE",
    16 "type": "WORK"
    17 }
    18 ]
    19 },
    20 "tracking_id": "testenterprices123122",
    21 "partner_config_override": {
    22 "partner_logo_url": "https://www.paypalobjects.com/webstatic/mktg/logo/pp_cc_mark_111x69.jpg",
    23 "return_url": "https://testenterprises.com/merchantonboarded",
    24 "return_url_description": "the url to return the merchant after the PayPal onboarding process.",
    25 "action_renewal_url": "https://testenterprises.com/renew-exprired-url",
    26 "show_add_credit_card": true
    27 },
    28 "operations": [
    29 {
    30 "operation": "API_INTEGRATION",
    31 "api_integration_preference": {
    32 "rest_api_integration": {
    33 "integration_method": "PAYPAL",
    34 "integration_type": "THIRD_PARTY",
    35 "third_party_details": {
    36 "features": [
    37 "PAYMENT",
    38 "REFUND",
    39 "PARTNER_FEE"
    40 ]
    41 }
    42 }
    43 }
    44 }
    45 ],
    46 "products": [
    47 "PAYMENT_METHODS"
    48 ],
    49 "capabilities": [
    50 "PAY_UPON_INVOICE"
    51 ],
    52 "legal_consents": [
    53 {
    54 "type": "SHARE_DATA_CONSENT",
    55 "granted": true
    56 }
    57 ]
    58}'

    Modify the code

    After you copy the code in the sample request, modify the following:

    • Change Access-Token to your access token.
    • Change PAYPAL-AUTH-ASSERTION to your PayPal-Auth-Assertion token.
    • Change BN-CODE to your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
    • It is possible to onboard a seller for the products PPCP and Pay Upon Invoice simultaneously. To offer this, your account must be configured for both products. In the above sample change products to ["PPCP", "PAYMENT_METHODS"] and capabilities to ["PAY_UPON_INVOICE"].
    • Prevent duplicate transactions by passing the PayPal-Request-Id parameter in the header of your /v2/checkout/orders requests.
    • Optional: Pass a tracking ID in the tracking_id field. You can use this ID to track the status of your seller as they complete onboarding.


    Response sample

      1{
      2 "links": [
      3 {
      4 "href": "https://api-m.sandbox.paypal.com/v2/customer/partner-referrals/ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      5 "rel": "self",
      6 "method": "GET",
      7 "description": "The read referral data shared by the partner."
      8 },
      9 {
      10 "href": "https://api-m.sandbox.paypal.com/bizsignup/partner/entry?referralToken=ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=",
      11 "rel": "action_url",
      12 "method": "GET",
      13 "description": "The target web redirect URL for the next action."
      14 }]
      15}

      A successful call returns a 201 created status. The following HATEOAS links are also returned:

      • A self link. You can make a GET request to this link to retrieve the referral data and to reinitialize the action_url.
      • An action_url link. You can place this link in a button or link tag to redirect your sellers to sign up with PayPal. The action_url expires after its first use. You can reinitialize it by making a GET request to the self link or by making another Partner Referrals API call.

      URL Onboarding

      Use URL onboarding only if you have already onboarded with URL onboarding or if you have a specific use case for URL onboarding. With URL onboarding, sellers are required to complete all sign-up fields. Sellers must also have a PayPal business account. Casual sellers are not supported.

      Example URL for Pay upon Invoice

        1https://www.sandbox.paypal.com/bizsignup/partner/entry?&partnerClientId=<var>&lt;partner_client_id&gt;</var>&partnerId=<var>&lt;partner_payer_id&gt;</var>&partnerLogoUrl=<var>&lt;partner_logo_url&gt;</var>&returnToPartnerUrl=<var>&lt;return_url_for_done_page_button&gt;</var>&product=payment_methods&capabilities=PAY_UPON_INVOICE&integrationType=FO&features=PAYMENT,REFUND&country.x=DE

        Example URL for enabling PPCP and Pay upon Invoice

          1https://www.sandbox.paypal.com/bizsignup/partner/entry?&partnerClientId=<var>&lt;partner_client_id&gt;</var>&partnerId=<var>&lt;partner_payer_id&gt;</var>&partnerLogoUrl=<var>&lt;partner_logo_url&gt;</var>&returnToPartnerUrl=<var>&lt;return_url_for_done_page_button&gt;</var>&product=ppcp&secondaryProducts=payment_methods&capabilities=PAY_UPON_INVOICE&integrationType=FO&features=PAYMENT,REFUND&country.x=DE

          Track Seller Onboarding Status

          You can track seller status by makings a show seller status call.

          Sample response for Pay Upon Invoice

            1{
            2 "merchant_id": "CG5RZJV4NR5P4",
            3 "tracking_id": "1537989077589",
            4 "products": [
            5 {
            6 "name": "PAYMENT_METHODS",
            7 "vetting_status": "SUBSCRIBED",
            8 "capabilities": [
            9 "PAY_UPON_INVOICE",
            10 "VAT_TAX",
            11 "PAY_WITH_PAYPAL"
            12 ]
            13 },
            14 ],
            15 "payments_receivable": true,
            16 "primary_email_confirmed": true,
            17 "products.vetting status": "SUBSCRIBED",
            18 "capabilities[name==PAY_UPON_INVOICE].status": "ACTIVE",
            19 "capabilities[name==PAY_UPON_INVOICE].limits": {
            20 "type": "GENERAL"
            21 },
            22 "oauth_integrations": [{
            23 "integration_type": "OAUTH_THIRD_PARTY",
            24 "integration_method": "PAYPAL",
            25 "oauth_third_party": [
            26 {
            27 "partner_client_id": "Af1bGDNgFBtbJvzEkG25zt4SoNQQ3ustiLm84GWXxe8nq_HE_0wCQ9SH8M1ScmSBURBIzPiCjr5gu-Dq",
            28 "merchant_client_id": "AQ7u3fJkUH4cdCEBidsh5U_F1RQCGjglJQdNEEsXCzvQsGsS5MmC8Dk7_ug_IlkUASJezaGqQxQQfVhQ",
            29 "scopes": ["https://uri.paypal.com/services/payments/realtimepayment", "https://uri.paypal.com/services/payments/refund", "https://uri.paypal.com/services/payments/payment/authcapture"]
            30 }
            31 ]
            32 }]
            33}
            2

            Create an order with Pay upon Invoice as the payment source

            Use the buyer information you captured from your user interface to create an order with Pay upon Invoice as the payment source.

            Sample request

            API endpoint used: Create order

              1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
              2-H "Content-Type: application/json" \
              3-H "Authorization: Bearer <Access-Token>" \
              4-H "PAYPAL-CLIENT-METADATA-ID: d4e0d7b9-4f75-43f9-9437-d8a57c901585" \
              5-d '{
              6 "intent": "CAPTURE",
              7 "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
              8 "purchase_units": [
              9 {
              10 "amount": {
              11 "currency_code": "EUR",
              12 "value": "100.00",
              13 "breakdown": {
              14 "item_total": {
              15 "currency_code": "EUR",
              16 "value": "81.00"
              17 },
              18 "tax_total": {
              19 "currency_code": "EUR",
              20 "value": "19.00"
              21 }
              22 }
              23 },
              24 "shipping": {
              25 "name": {
              26 "full_name": "John Doe"
              27 },
              28 "address": {
              29 "address_line_1": "Taunusanlage 12",
              30 "admin_area_2": "FRANKFURT AM MAIN",
              31 "postal_code": "60325",
              32 "country_code": "DE"
              33 }
              34 },
              35 "items": [
              36 {
              37 "name": "Air Jordan Shoe",
              38 "category": "PHYSICAL_GOODS",
              39 "unit_amount": {
              40 "currency_code": "EUR",
              41 "value": "81.00"
              42 },
              43 "tax": {
              44 "currency_code": "EUR",
              45 "value": "19.00"
              46 },
              47 "tax_rate": "19.00",
              48 "quantity": "1"
              49 }
              50 ],
              51 "invoice_id": "MERCHANT_INVOICE_ID",
              52 "custom_id": "MERCHANT_CUSTOM_ID"
              53 }
              54 ],
              55 "payment_source": {
              56 "pay_upon_invoice": {
              57 "name": {
              58 "given_name": "John",
              59 "surname": "Doe"
              60 },
              61 "email": "buyer@example.com",
              62 "birth_date": "1990-01-01",
              63 "phone": {
              64 "national_number": "6912345678",
              65 "country_code": "49"
              66 },
              67 "billing_address": {
              68 "address_line_1": "Schönhauser Allee 84",
              69 "admin_area_2": "Berlin",
              70 "postal_code": "10439",
              71 "country_code": "DE"
              72 },
              73 "experience_context": {
              74 "locale": "en-DE",
              75 "brand_name": "EXAMPLE INC",
              76 "logo_url": "https://example.com/logoUrl.svg",
              77 "customer_service_instructions": [
              78 "Customer service phone is +49 6912345678."
              79 ]
              80 }
              81 }
              82 }
              83}'

              Modify the code

              After you copy the code in the sample request, modify the following:

              • Access-Token - Your access token.
              • PAYPAL-AUTH-ASSERTION: Your PayPal-Auth-Assertion token.
              • BN-CODE: Your PayPal Attribution ID to receive revenue attribution. To find your BN code, see Code and Credential Reference.
              • intent - This parameter must be set to CAPTURE as it is in this sample code.
              • purchase_units: amount - Pass the amount of the order and the currency code.
              • purchase_units: items - Pass the name, category, unit amount, tax amount and tax rate of various items in the order. Please note: only items from the category PHYSICAL_GOODS are permissible for Pay Upon Invoice. If items that do not belong in this category are wrongfully tagged as such, the transaction can be reversed.
              • purchase_units: shipping - Pass the optional shipping name and address.
              • payment_source - Specify the following:
                • pay_upon_invoice as the payment_source and include the country_code.
                • Account holder's name on name field.
                • Account holder's email on email field.
                • Account holder's date of birth on birth_date field.
                • Account holder's phone number on phone field.
                • Account holder's billing address on billing_address field.
                • experience_context - Specify preferred language, brand name, logo, and customer service instructions to be presented on Ratepay's payment instruction email sent to the buyer. Currently, you can only use German as the preferred language (locale=de-DE).
              • processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL as it is in this sample code.
              • invoice_id - Pass the optional invoice number that identifies the order in your system. This order ID shows up in the payment instruction email that Ratepay sends to the buyer. We recommend that you pass this value to help Ratepay communicate with the buyer. If your request doesn't pass a value for invoice_id, Ratepay's payment instruction email shows the id value of the PayPal checkout order resource. For this reason, the invoice_id value can't be modified after Step 3.
              • Optional: Change or add other parameters in the Create order request body to create an order that reflects the actual order details.

              Step result

              A successful request results in the following:

              • A return status code of HTTP 201 Created.
              • A JSON response body that contains the order ID. You'll use the order ID in the next step.

              This indicates that Ratepay performed the buyer risk assessment successfully and approved the payment.

              When the status returns PENDING_APPROVAL, display a message to the buyer that indicates that checkout is complete. The order was confirmed, and the payer action has been completed, but the order approval process from PayPal is pending. No action is needed from the payee or payer. In Step 4, listen to the webhooks to get the result of the order capture, so you can notify the buyer offline of a successful or failed transaction.

              Sample response

                1{
                2 "id": "5O190127TN364715T",
                3 "status": "PENDING_APPROVAL",
                4 "payment_source": {
                5 "pay_upon_invoice": {
                6 "birth_date": "1990-01-01",
                7 "name": {
                8 "given_name": "John",
                9 "surname": "Doe"
                10 },
                11 "email": "buyer@example.com",
                12 "phone": {
                13 "national_number": "6912345678",
                14 "country_code": "49"
                15 },
                16 "billing_address": {
                17 "address_line_1": "Schönhauser Allee 84",
                18 "admin_area_2": "Berlin",
                19 "postal_code": "10439",
                20 "country_code": "DE"
                21 }
                22 }
                23 },
                24 "links": [
                25 {
                26 "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                27 "rel": "self",
                28 "method": "GET"
                29 }
                30 ]
                31}
                3

                Listen to webhooks to get the result of order capture

                Listen to the following webhooks to get the result of order capture

                • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.
                • The PAYMENT.CAPTURE.DENIED and CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook events indicate a failed order capture.

                Getting the result might be delayed by a few moments.

                Sample PAYMENT.CAPTURE.COMPLETED webhook

                  1{
                  2 "id": "WH-6WA12701B00483532-15737896PW730511B",
                  3 "event_version": "1.0",
                  4 "create_time": "2021-03-19T08:07:57.563Z",
                  5 "resource_type": "capture",
                  6 "resource_version": "2.0",
                  7 "event_type": "PAYMENT.CAPTURE.COMPLETED",
                  8 "summary": "Payment completed for EUR 1.0 EUR",
                  9 "resource": {
                  10 "id": "84745544P6340640G",
                  11 "status": "COMPLETED",
                  12 "amount": {
                  13 "value": "100.00",
                  14 "currency_code": "EUR"
                  15 },
                  16 "seller_receivable_breakdown": {
                  17 "paypal_fee": {
                  18 "value": "3.00",
                  19 "currency_code": "EUR"
                  20 },
                  21 "gross_amount": {
                  22 "value": "100.00",
                  23 "currency_code": "EUR"
                  24 },
                  25 "net_amount": {
                  26 "value": "97.00",
                  27 "currency_code": "EUR"
                  28 }
                  29 },
                  30 "custom_id": "MERCHANT_CUSTOM_ID",
                  31 "invoice_id": "MERCHANT_INVOICE_ID",
                  32 "seller_protection": {
                  33 "status": "NOT_ELIGIBLE"
                  34 },
                  35 "supplementary_data": {
                  36 "related_ids": {
                  37 "order_id": "5O190127TN364715T"
                  38 }
                  39 },
                  40 "update_time": "2021-03-19T08:07:40Z",
                  41 "create_time": "2021-03-19T08:06:45Z",
                  42 "final_capture": true,
                  43 "links": [
                  44 {
                  45 "method": "GET",
                  46 "rel": "self",
                  47 "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/826413372K501814R"
                  48 },
                  49 {
                  50 "method": "POST",
                  51 "rel": "refund",
                  52 "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/826413372K501814R/refund"
                  53 },
                  54 {
                  55 "method": "GET",
                  56 "rel": "up",
                  57 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T"
                  58 }
                  59 ]
                  60 },
                  61 "links": [
                  62 {
                  63 "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6WA12701B00483532-15737896PW730511B",
                  64 "rel": "self",
                  65 "method": "GET"
                  66 },
                  67 {
                  68 "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6WA12701B00483532-15737896PW730511B/resend",
                  69 "rel": "resend",
                  70 "method": "POST"
                  71 }
                  72 ]
                  73}

                  The order ID from Step 3 should match resource.supplementary_data.related_ids.order_id parameter in the webhook payload.

                  Sample PAYMENT.CAPTURE.DENIED webhook

                    1{
                    2 "id": "WH-11M70257FM3776948-8B478027S4286991F",
                    3 "event_version": "1.0",
                    4 "create_time": "2021-03-19T08:17:29.782Z",
                    5 "resource_type": "capture",
                    6 "resource_version": "2.0",
                    7 "event_type": "PAYMENT.CAPTURE.DENIED",
                    8 "summary": "Payment denied for EUR 100.0 EUR",
                    9 "resource": {
                    10 "id": "826413372K501814R",
                    11 "status": "DECLINED",
                    12 "amount": {
                    13 "value": "100.00",
                    14 "currency_code": "EUR"
                    15 },
                    16 "seller_receivable_breakdown": {
                    17 "gross_amount": {
                    18 "value": "100.00",
                    19 "currency_code": "EUR"
                    20 },
                    21 "net_amount": {
                    22 "value": "100.00",
                    23 "currency_code": "EUR"
                    24 }
                    25 },
                    26 "custom_id": "MERCHANT_CUSTOM_ID",
                    27 "invoice_id": "MERCHANT_INVOICE_ID",
                    28 "seller_protection": {
                    29 "status": "NOT_ELIGIBLE"
                    30 },
                    31 "supplementary_data": {
                    32 "related_ids": {
                    33 "order_id": "5O190127TN364715T"
                    34 }
                    35 },
                    36 "update_time": "2021-03-19T08:17:12Z",
                    37 "create_time": "2021-03-19T08:16:01Z",
                    38 "final_capture": true,
                    39 "links": [
                    40 {
                    41 "method": "GET",
                    42 "rel": "self",
                    43 "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/826413372K501814R"
                    44 },
                    45 {
                    46 "method": "POST",
                    47 "rel": "refund",
                    48 "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/826413372K501814R/refund"
                    49 },
                    50 {
                    51 "method": "GET",
                    52 "rel": "up",
                    53 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T"
                    54 }
                    55 ]
                    56 },
                    57 "links": [
                    58 {
                    59 "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-11M70257FM3776948-8B478027S4286991F",
                    60 "rel": "self",
                    61 "method": "GET"
                    62 },
                    63 {
                    64 "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-11M70257FM3776948-8B478027S4286991F/resend",
                    65 "rel": "resend",
                    66 "method": "POST"
                    67 }
                    68 ]
                    69}

                    The order ID from Step 3 should match resource.supplementary_data.related_ids.order_id parameter in the webhook payload.

                    Sample CHECKOUT.PAYMENT-APPROVAL.REVERSED webhook

                      1{
                      2 "id": "WH-COC11055RA711503B-4YM959094A144403T",
                      3 "create_time": "2021-03-19T08:17:29.782Z",
                      4 "event_type": "CHECKOUT.PAYMENT-APPROVAL.REVERSED",
                      5 "summary": "A payment has been reversed after approval.",
                      6 "resource": {
                      7 "order_id": "5O190127TN364715T",
                      8 "purchase_units": [
                      9 {
                      10 "custom_id": "MERCHANT_CUSTOM_ID",
                      11 "invoice_id": "MERCHANT_INVOICE_ID"
                      12 }
                      13 ],
                      14 "payment_source": {
                      15 "pay_upon_invoice": {
                      16 "birth_date": "1990-01-01",
                      17 "name": {
                      18 "given_name": "John",
                      19 "surname": "Doe"
                      20 },
                      21 "email": "buyer@example.com",
                      22 "phone": {
                      23 "national_number": "6912345678",
                      24 "country_code": "49"
                      25 },
                      26 "billing_address": {
                      27 "address_line_1": "Schönhauser Allee 84",
                      28 "admin_area_2": "Berlin",
                      29 "postal_code": "10439",
                      30 "country_code": "DE"
                      31 }
                      32 }
                      33 }
                      34 },
                      35 "event_version": "1.0"
                      36}

                      The order ID from Step 3 should match resource.order_id parameter in the webhook payload.

                      Alternatively, if your app misses the webhook needed to capture the order, you can get the order capture result by sending a GET call to the Show order details endpoint of the Orders v2 API.

                      Sample request

                        1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
                        2 -H "Content-Type: application/json" \
                        3 -H "Authorization: Bearer <Access-Token>"

                        Sample response

                          1{
                          2 "id": "5O190127TN364715T",
                          3 "intent": "CAPTURE",
                          4 "status": "COMPLETED",
                          5 "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
                          6 "payment_source": {
                          7 "pay_upon_invoice": {
                          8 "birth_date": "1990-01-01",
                          9 "name": {
                          10 "given_name": "John",
                          11 "surname": "Doe"
                          12 },
                          13 "email": "buyer@example.com",
                          14 "phone": {
                          15 "national_number": "6912345678",
                          16 "country_code": "49"
                          17 },
                          18 "billing_address": {
                          19 "address_line_1": "Schönhauser Allee 84",
                          20 "admin_area_2": "Berlin",
                          21 "postal_code": "10439",
                          22 "country_code": "DE"
                          23 },
                          24 "payment_reference": "b8a1525dlYzu6Mn62umI",
                          25 "deposit_bank_details": {
                          26 "bic": "DEUTDEFFXXX",
                          27 "bank_name": "Deutsche Bank",
                          28 "iban": "DE89370400440532013000",
                          29 "account_holder_name": "Paypal - Ratepay GmbH - Test Bank Account"
                          30 }
                          31 }
                          32 },
                          33 "purchase_units": [
                          34 {
                          35 "invoice_id": "MERCHANT_INVOICE_ID",
                          36 "custom_id": "MERCHANT_CUSTOM_ID",
                          37 "amount": {
                          38 "currency_code": "EUR",
                          39 "value": "100.00",
                          40 "breakdown": {
                          41 "item_total": {
                          42 "currency_code": "EUR",
                          43 "value": "81.00"
                          44 },
                          45 "tax_total": {
                          46 "currency_code": "EUR",
                          47 "value": "19.00"
                          48 }
                          49 }
                          50 },
                          51 "shipping": {
                          52 "name": {
                          53 "full_name": "John Doe"
                          54 },
                          55 "address": {
                          56 "address_line_1": "Taunusanlage 12",
                          57 "admin_area_2": "FRANKFURT AM MAIN",
                          58 "postal_code": "60325",
                          59 "country_code": "DE"
                          60 }
                          61 },
                          62 "items": [
                          63 {
                          64 "name": "Air Jordan Shoe",
                          65 "category": "PHYSICAL_GOODS",
                          66 "unit_amount": {
                          67 "currency_code": "EUR",
                          68 "value": "100.00"
                          69 },
                          70 "tax": {
                          71 "currency_code": "EUR",
                          72 "value": "19.00"
                          73 },
                          74 "tax_rate": "19.00",
                          75 "quantity": "1"
                          76 }
                          77 ],
                          78 "payments": {
                          79 "captures": [
                          80 {
                          81 "id": "826413372K501814R",
                          82 "status": "COMPLETED",
                          83 "amount": {
                          84 "currency_code": "EUR",
                          85 "value": "100.00"
                          86 },
                          87 "final_capture": true,
                          88 "seller_protection": {
                          89 "status": "NOT_ELIGIBLE"
                          90 },
                          91 "seller_receivable_breakdown": {
                          92 "gross_amount": {
                          93 "currency_code": "EUR",
                          94 "value": "100.00"
                          95 },
                          96 "paypal_fee": {
                          97 "currency_code": "EUR",
                          98 "value": "3.00"
                          99 },
                          100 "net_amount": {
                          101 "currency_code": "EUR",
                          102 "value": "97.00"
                          103 }
                          104 },
                          105 "invoice_id": "MERCHANT_INVOICE_ID",
                          106 "custom_id": "MERCHANT_CUSTOM_ID",
                          107 "links": [
                          108 {
                          109 "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
                          110 "rel": "self",
                          111 "method": "GET"
                          112 },
                          113 {
                          114 "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                          115 "rel": "up",
                          116 "method": "GET"
                          117 },
                          118 {
                          119 "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
                          120 "rel": "refund",
                          121 "method": "POST"
                          122 }
                          123 ],
                          124 "create_time": "2021-03-19T08:16:01Z",
                          125 "update_time": "2021-03-19T08:17:12Z"
                          126 }
                          127 ]
                          128 }
                          129 }
                          130 ],
                          131 "links": [
                          132 {
                          133 "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                          134 "rel": "self",
                          135 "method": "GET"
                          136 }
                          137 ]
                          138}

                          Step result

                          A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

                          A successfully captured order has the following:

                          • The order status as COMPLETED, which means the order was captured successfully.
                          • A capture with COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0]. The up HATEOAS link indicates the order associated with this capture.
                          4

                          Notify buyer of success

                          Notify the buyer of the successful transaction offline and send the instructions to pay the invoice. Obtain these instructions on a per transaction basis from the Show order details endpoint. The payment reference is present in payment_source.pay_upon_invoice.payment_reference response parameter. Buyer needs to enter this value in the reason for transfer (dt. Verwendungszweck) during bank transfer. The deposit bank information is present in the payment_source.pay_upon_invoice.deposit_bank_details response parameter.

                          Sample request

                            1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
                            2 -H "Content-Type: application/json" \
                            3 -H "Authorization: Bearer <Access-Token>"

                            Sample response

                              1{
                              2 "id": "5O190127TN364715T",
                              3 "intent": "CAPTURE",
                              4 "status": "COMPLETED",
                              5 "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
                              6 "payment_source": {
                              7 "pay_upon_invoice": {
                              8 "birth_date": "1990-01-01",
                              9 "name": {
                              10 "given_name": "John",
                              11 "surname": "Doe"
                              12 },
                              13 "email": "buyer@example.com",
                              14 "phone": {
                              15 "national_number": "6912345678",
                              16 "country_code": "49"
                              17 },
                              18 "billing_address": {
                              19 "address_line_1": "Schönhauser Allee 84",
                              20 "admin_area_2": "Berlin",
                              21 "postal_code": "10439",
                              22 "country_code": "DE"
                              23 },
                              24 "payment_reference": "b8a1525dlYzu6Mn62umI",
                              25 "deposit_bank_details": {
                              26 "bic": "DEUTDEFFXXX",
                              27 "bank_name": "Deutsche Bank",
                              28 "iban": "DE89370400440532013000",
                              29 "account_holder_name": "Paypal - Ratepay GmbH - Test Bank Account"
                              30 }
                              31 }
                              32 },
                              33 "purchase_units": [
                              34 {
                              35 "invoice_id": "MERCHANT_INVOICE_ID",
                              36 "custom_id": "MERCHANT_CUSTOM_ID",
                              37 "amount": {
                              38 "currency_code": "EUR",
                              39 "value": "100.00",
                              40 "breakdown": {
                              41 "item_total": {
                              42 "currency_code": "EUR",
                              43 "value": "81.00"
                              44 },
                              45 "tax_total": {
                              46 "currency_code": "EUR",
                              47 "value": "19.00"
                              48 }
                              49 }
                              50 },
                              51 "shipping": {
                              52 "name": {
                              53 "full_name": "John Doe"
                              54 },
                              55 "address": {
                              56 "address_line_1": "Taunusanlage 12",
                              57 "admin_area_2": "FRANKFURT AM MAIN",
                              58 "postal_code": "60325",
                              59 "country_code": "DE"
                              60 }
                              61 },
                              62 "items": [
                              63 {
                              64 "name": "Air Jordan Shoe",
                              65 "category": "PHYSICAL_GOODS",
                              66 "unit_amount": {
                              67 "currency_code": "EUR",
                              68 "value": "100.00"
                              69 },
                              70 "tax": {
                              71 "currency_code": "EUR",
                              72 "value": "19.00"
                              73 },
                              74 "tax_rate": "19.00",
                              75 "quantity": "1"
                              76 }
                              77 ],
                              78 "payments": {
                              79 "captures": [
                              80 {
                              81 "id": "826413372K501814R",
                              82 "status": "COMPLETED",
                              83 "amount": {
                              84 "currency_code": "EUR",
                              85 "value": "100.00"
                              86 },
                              87 "final_capture": true,
                              88 "seller_protection": {
                              89 "status": "NOT_ELIGIBLE"
                              90 },
                              91 "seller_receivable_breakdown": {
                              92 "gross_amount": {
                              93 "currency_code": "EUR",
                              94 "value": "100.00"
                              95 },
                              96 "paypal_fee": {
                              97 "currency_code": "EUR",
                              98 "value": "3.00"
                              99 },
                              100 "net_amount": {
                              101 "currency_code": "EUR",
                              102 "value": "97.00"
                              103 }
                              104 },
                              105 "invoice_id": "MERCHANT_INVOICE_ID",
                              106 "custom_id": "MERCHANT_CUSTOM_ID",
                              107 "links": [
                              108 {
                              109 "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
                              110 "rel": "self",
                              111 "method": "GET"
                              112 },
                              113 {
                              114 "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                              115 "rel": "up",
                              116 "method": "GET"
                              117 },
                              118 {
                              119 "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
                              120 "rel": "refund",
                              121 "method": "POST"
                              122 }
                              123 ],
                              124 "create_time": "2021-03-19T08:16:01Z",
                              125 "update_time": "2021-03-19T08:17:12Z"
                              126 }
                              127 ]
                              128 }
                              129 }
                              130 ],
                              131 "links": [
                              132 {
                              133 "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
                              134 "rel": "self",
                              135 "method": "GET"
                              136 }
                              137 ]
                              138}

                              Step result

                              A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

                              A successfully captured order has the following:

                              • The order status is COMPLETED, which means the order was captured successfully.
                              • A capture with COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0]. The up HATEOAS link indicates the order associated with this capture.
                              • The payment reference is present in payment_source.pay_upon_invoice.payment_reference response parameter. Buyer needs to enter this value in the reason (dt. Verwendungszweck) during the bank transfer.
                              • The deposit bank information is present in the payment_source.pay_upon_invoice.deposit_bank_details response parameter.

                              Send an invoice to the buyer including the payment instructions as received on a per transaction basis pointing out that payment must be made to Ratepay.

                              Display the appropriate error message to the buyer

                              Step 1 when unsuccessful returns the HTTP 422 UNPROCESSABLE_ENTITY status code with a JSON response body that contains an error code in the issue parameter.

                              Sample request

                              API endpoint used: Create order

                                1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
                                2-H "Content-Type: application/json" \
                                3-H "Authorization: Bearer <Access-Token>" \
                                4-H "PAYPAL-CLIENT-METADATA-ID: d4e0d7b9-4f75-43f9-9437-d8a57c901585" \
                                5-d '{
                                6 "intent": "CAPTURE",
                                7 "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
                                8 "purchase_units": [
                                9 {
                                10 "amount": {
                                11 "currency_code": "EUR",
                                12 "value": "100.00",
                                13 "breakdown": {
                                14 "item_total": {
                                15 "currency_code": "EUR",
                                16 "value": "81.00"
                                17 },
                                18 "tax_total": {
                                19 "currency_code": "EUR",
                                20 "value": "19.00"
                                21 }
                                22 }
                                23 },
                                24 "shipping": {
                                25 "name": {
                                26 "full_name": "John Doe"
                                27 },
                                28 "address": {
                                29 "address_line_1": "Taunusanlage 12",
                                30 "admin_area_2": "FRANKFURT AM MAIN",
                                31 "postal_code": "60325",
                                32 "country_code": "DE"
                                33 }
                                34 },
                                35 "items": [
                                36 {
                                37 "name": "Air Jordan Shoe",
                                38 "category": "PHYSICAL_GOODS",
                                39 "unit_amount": {
                                40 "currency_code": "EUR",
                                41 "value": "81.00"
                                42 },
                                43 "tax": {
                                44 "currency_code": "EUR",
                                45 "value": "19.00"
                                46 },
                                47 "tax_rate": "19.00",
                                48 "quantity": "1"
                                49 }
                                50 ],
                                51 "invoice_id": "MERCHANT_INVOICE_ID",
                                52 "custom_id": "MERCHANT_CUSTOM_ID"
                                53 }
                                54 ],
                                55 "payment_source": {
                                56 "pay_upon_invoice": {
                                57 "name": {
                                58 "given_name": "John",
                                59 "surname": "Doe"
                                60 },
                                61 "email": "payment_source_info_cannot_be_verified@example.com",
                                62 "birth_date": "1990-01-01",
                                63 "phone": {
                                64 "national_number": "6912345678",
                                65 "country_code": "49"
                                66 },
                                67 "billing_address": {
                                68 "address_line_1": "Schönhauser Allee 84",
                                69 "admin_area_2": "Berlin",
                                70 "postal_code": "10439",
                                71 "country_code": "DE"
                                72 },
                                73 "experience_context": {
                                74 "locale": "en-DE",
                                75 "brand_name": "EXAMPLE INC",
                                76 "logo_url": "https://example.com/logoUrl.svg",
                                77 "customer_service_instructions": [
                                78 "Customer service phone is +49 6912345678."
                                79 ]
                                80 }
                                81 }
                                82 }
                                83}'

                                Step result

                                An unsuccessful request results in the following:

                                • A return status code of HTTP 422 Unprocessable Entity.
                                • A JSON response body that contains an error code in the issue parameter and the error description in the description parameter.

                                Sample response

                                  1{
                                  2 "name": "UNPROCESSABLE_ENTITY",
                                  3 "details": [
                                  4 {
                                  5 "issue": "PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED",
                                  6 "description": "The combination of the payment_source name, billing address, shipping name and shipping address could not be verified. Please correct this information and try again by creating a new order."
                                  7 }
                                  8 ],
                                  9 "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
                                  10 "debug_id": "82c4e721e5c58",
                                  11 "links": [
                                  12 {
                                  13 "href": "https://developer.paypal.com/api/orders/v2/#error-PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED",
                                  14 "rel": "information_link",
                                  15 "method": "GET"
                                  16 }
                                  17 ]
                                  18}

                                  Duplicate orders

                                  When a duplicate order is detected, the Orders API declines the order and returns the following error code and description:

                                  Error code: PUI_DUPLICATE_ORDER
                                  Error description: A Pay Upon Invoice (Rechnungskauf) order with the same payload has already been successfully processed in the last few seconds. To process a new order, please try again in a few seconds.

                                  Error codes and corresponding error messages to be displayed to the buyer

                                  RatePay mandates that you display the error messages to the buyer as described in the below table for the following error codes.

                                  Error code Error message (English) Error message (German)
                                  PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED The combination of your name and address could not be validated. Please correct your data and try again. You can find further information in the Ratepay Data Privacy Statement or you can contact Ratepay using this contact form. Die Kombination aus Ihrem Namen und Ihrer Anschrift konnte nicht validiert werden. Bitte korrigieren Sie Ihre Daten und versuchen Sie es erneut. Weitere Informationen finden Sie in den Ratepay Datenschutzbestimmungen oder nutzen Sie das Ratepay Kontaktformular.
                                  PAYMENT_SOURCE_DECLINED_BY_PROCESSOR It is not possible to use the selected payment method. This decision is based on automated data processing. You can find further information in the Ratepay Data Privacy Statement or you can contact Ratepay using this contact form. Die gewählte Zahlungsart kann nicht genutzt werden. Diese Entscheidung basiert auf einem automatisierten Datenverarbeitungsverfahren. Weitere Informationen finden Sie in den Ratepay Datenschutzbestimmungen oder nutzen Sie das Ratepay Kontaktformular.



                                  Test your integration

                                  Use these buyer email addresses to simulate the failure scenarios in the PayPal sandbox environment.

                                  Error code Buyer email
                                  PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED payment_source_info_cannot_be_verified@example.com
                                  PAYMENT_SOURCE_DECLINED_BY_PROCESSOR payment_source_declined_by_processor@example.com
                                  PAYMENT_SOURCE_CANNOT_BE_USED payment_source_cannot_be_used@example.com
                                  BILLING_ADDRESS_INVALID billing_address_invalid@example.com
                                  SHIPPING_ADDRESS_INVALID shipping_address_invalid@example.com

                                  Any buyer email not listed in the table will simulate a successful scenario on PayPal sandbox environment.

                                  If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more