Requests

      Requests


        Article Summary

        Pay

        The default action for PayPal is Pay. This action has no required input. Optional input includes the PayPal account e-mail address of the consumer, a PayPal page style and/or a Billing Agreement Description. Upon receiving the request, the consumer will be redirected to PayPal for verification and confirmation of the payment and/or billing agreement. A successful payment will include the PayPal account status of the consumer (e.g. verified or unverified), the notetext (if entered by the consumer at PayPal under ‘note to seller’), his e-mail address used as PayPal account, and the country of the consumer.

        Base JSON request

        Use the base request as instructed on this page

        Pay request

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        BuyerEmailStringNoN/AE-mail address the consumer uses for his PayPal account.
        ProductNameStringNoN/AIn the Paypal payment pages, an overview is shown containing the payment details. If no productname is provided the description is shown there as productname. If a productname is provided, the Productname is shown with the description as a product description.
        BillingAgreementDescriptionStringA description used for a billing agreement. Provide this if performing recurrent billing. If not provided, the transaction description is used for both the initial payment and the billing agreement. Make sure the description is an accurate depiction of the subscription or service (e.g. ‘2 Year subscription for 24 issues of Magazine X’). This can be 127 characters max.
        PageStyleStringThe page style as defined in the merchant PayPal account.
        startrecurrentbooleanSet startrecurrent to true to start the first transaction in a series of recurrent transactions. This will require the consumer to accept a billing agreement when performing the initial transaction. Please note: This is a basic request variable, not a service specific variable.
        PayPalOrderIdStringPayPal Order ID, required for the implementation of the Express Checkout functionality. Also see Client SDK - PayPal Express Checkout
        Basic parameters

        Example request

        {
          "Currency": "EUR",
          "AmountDebit": 10.00,
          "Invoice": "testinvoice 123",
          "Services": {
            "ServiceList": [
              {
                "Name": "paypal",
                "Action": "Pay",
                "Parameters": [
                  {
                    "Name": "PayPalOrderId",
                    "Value": "XXXXXX"
                  }
                ]
              }
            ]
          }
        }
        

        Pay response

        If the request has a valid structure and a valid signature, a transaction will be created in the Payment Engine and a response will be returned. In this case, an additional action is required before the transaction can be completed. The customer needs to be redirected to the payment environment through the returned redirect URL.

        Parameters

        Basic parameters

        Example response

        {
          "Key": "2D04704995B74D679AACC59F87XXXXXX",
          "Status": {
            "Code": {
              "Code": 791,
              "Description": "Pending processing"
            },
            "SubCode": {
              "Code": "S002",
              "Description": "An additional action is required: PayPal ExpressCheckout"
            },
            "DateTime": "2017-03-28T15:58:56"
          },
          "RequiredAction": {
            "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=D3490B0DF2454F46A1D0E80065XXXXXX",
            "RequestedInformation": null,
            "PayRemainderDetails": null,
            "Name": "Redirect",
            "TypeDeprecated": 0
          },
        "Services": [
                {
                    "Name": "paypal",
                    "Action": null,
                    "Parameters": [
                        {
                            "Name": "orderId",
                            "Value": "3C786053MK04XXXXX"
                        }
                    ]
                }
            ],
          "Services": null,
          "CustomParameters": null,
          "AdditionalParameters": null,
          "RequestErrors": null,
          "Invoice": "testinvoice 123",
          "ServiceCode": "paypal",
          "IsTest": true,
          "Currency": "EUR",
          "AmountDebit": 10.0,
          "TransactionType": "V010",
          "MutationType": 2,
          "RelatedTransactions": null,
          "ConsumerMessage": null,
          "Order": null,
          "IssuingCountry": null,
          "StartRecurrent": false,
          "Recurring": false,
          "CustomerName": null,
          "PayerHash": null,
          "PaymentKey": "9E66009180A245F99987E4972AXXXXXX"
        }
        

        Pay push

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        payerStatusStringN/AN/AThe account status of the consumers PayPal account. Can be ‘Verified’ or ‘Unverified’
        noteTextStringN/AN/AThe text a consumer can optionally enter at the PayPal payment page during the acceptance of the payment.
        payerEmailStringN/AN/AThe email address of the PayPal account of the consumer.
        payerCountryStringN/AN/AThe countrycode of the consumer (2-letter ISO country code, e.g. NL)
        payerfirstnameStringN/AN/AThe first name of the PayPal account of the consumer.
        payerlastnameStringN/AN/AThe last name of the PayPal account of the consumer.
        payertransactionidStringN/AN/AThe unique number given by PayPal.
        Basic parameters

        Example push

        {
          "Transaction": {
            "Key": "2D04704995B74D679AACC59F87XXXXXX",
            "Invoice": "testinvoice 123",
            "ServiceCode": "paypal",
            "Status": {
              "Code": {
                "Code": 190,
                "Description": "Success"
              },
              "SubCode": {
                "Code": "P904",
                "Description": "The PayPal payment has been completed."
              },
              "DateTime": "2017-03-28T16:00:04"
            },
            "IsTest": true,
            "Order": null,
            "Currency": "EUR",
            "AmountDebit": 10,
            "TransactionType": "V010",
            "Services": [
              {
                "Name": "paypal",
                "Action": null,
                "Parameters": [
                  {
                    "Name": "payerEmail",
                    "Value": "johnsmith@gmail.com"
                  },
                  {
                    "Name": "payerCountry",
                    "Value": "NL"
                  },
                  {
                    "Name": "payerStatus",
                    "Value": "unverified"
                  },
                  {
                    "Name": "payerFirstname",
                    "Value": "John"
                  },
                  {
                    "Name": "payerLastname",
                    "Value": "Smith"
                  },
                  {
                    "Name": "paypalTransactionID",
                    "Value": "7BS177612A528273"
                  }
                ],
                "VersionAsProperty": 1
              }
            ],
            "CustomParameters": null,
            "AdditionalParameters": null,
            "MutationType": 2,
            "RelatedTransactions": null,
            "IsCancelable": false,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": false,
            "CustomerName": "John Smith",
            "PayerHash": null,
            "PaymentKey": "9E66009180A245F99987E4972AXXXXXX"
          }
        }
        

        Refund

        To refund a successful PayPal transaction, use the action Refund. A refund is then performed through PayPal which transfers the amount of the original transaction to the consumers PayPal account.

        Refund request

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        originaltransactionStringYesN/ATransaction key of the original transaction that needs to be refunded. Please note: This is a basic request variable, not a service specific variable. This is a 32-charcater hex string.
        Basic parameters

        Example request

        {
          "Currency": "EUR",
          "AmountCredit": 1.00,
          "Invoice": "testinvoice 123",
          "OriginalTransactionKey": "2D04704995B74D679AACC59F87XXXXXX",
          "Services": {
            "ServiceList": [
              {
                "Name": "paypal",
                "Action": "Refund"
              }
            ]
          }
        }
        

        Refund response

        Parameters

        Basic parameters

        Example response

        {
            "Key": "1C23FD5003FA407297A39C46D0XXXXXX",
            "Status": {
                "Code": {
                    "Code": 190,
                    "Description": "Success"
                },
                "SubCode": {
                    "Code": "S001",
                    "Description": "Transaction successfully processed"
                },
                "DateTime": "2017-03-30T11:41:03"
            },
            "RequiredAction": null,
            "Services": null,
            "CustomParameters": null,
            "AdditionalParameters": null,
            "RequestErrors": null,
            "Invoice": "testinvoice 123",
            "ServiceCode": "paypal",
            "IsTest": true,
            "Currency": "EUR",
            "AmountCredit": 1,
            "TransactionType": "V110",
            "MutationType": 2,
            "RelatedTransactions": [
                {
                    "RelationType": "refund",
                    "RelatedTransactionKey": "2D04704995B74D679AACC59F87XXXXXX"
                }
            ],
            "ConsumerMessage": null,
            "Order": null,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": false,
            "CustomerName": "T. Tester",
            "PayerHash": null,
            "PaymentKey": "BFFB19D7C97E46C39A4583135BXXXXXX"
        }
        

        Refund push

        Parameters

        Basic parameters

        Example request

        {
          "Transaction": {
            "Key": "1C23FD5003FA407297A39C46D0XXXXXX",
            "Invoice": "testinvoice 123",
            "ServiceCode": "paypal",
            "Status": {
              "Code": {
                "Code": 190,
                "Description": "Success"
              },
              "SubCode": {
                "Code": "S001",
                "Description": "Transaction successfully processed"
              },
              "DateTime": "2017-03-30T11:41:03"
            },
            "IsTest": true,
            "Order": null,
            "Currency": "EUR",
            "AmountCredit": 1,
            "TransactionType": "V110",
            "Services": null,
            "CustomParameters": null,
            "AdditionalParameters": null,
            "MutationType": 2,
            "RelatedTransactions": [
              {
                "RelationType": "refund",
                "RelatedTransactionKey": "2D04704995B74D679AACC59F87XXXXXX"
              }
            ],
            "IsCancelable": false,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": false,
            "CustomerName": "T. Tester",
            "PayerHash": null,
            "PaymentKey": "BFFB19D7C97E46C39A4583135BXXXXXX"
          }
        }
        

        PayRecurrent

        To perform a recurrent PayPal transaction, use the action PayRecurrent. A payment is then performed through PayPal. To be able to perform a successful recurrent payment, a successful initial payment must be available, that has been performed through the ‘Pay’ action, using option ‘startrecurrent’ and optionally supplying a billing agreement description.

        Payrecurrent request

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        originaltransactionStringYesN/AThe key of the transaction that needs to be used to perform a new transaction.
        Basic parameters

        Example request

        {
          "Currency": "EUR",
          "AmountDebit": 10.00,
          "Invoice": "testinvoice 123",
          "OriginalTransactionKey": "C32C0B52E1FE4A37835FFB1716XXXXXX",
          "Services": {
            "ServiceList": [
              {
                "Name": "paypal",
                "Action": "PayRecurrent"
              }
            ]
          }
        }
        

        PayRecurrent response

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        payerStatusStringN/AN/AThe account status of the consumers PayPal account. Can be ‘Verified’ or ‘Unverified’
        payerEmailStringN/AN/AThe email address of the PayPal account of the consumer.
        payerCountryStringN/AN/AThe countrycode of the consumer (2-letter ISO country code, e.g. NL)
        payerfirstnameStringN/AN/AThe first name of the PayPal account of the consumer.
        payerlastnameStringN/AN/AThe last name of the PayPal account of the consumer.
        payertransactionidStringN/AN/AThe unique number given by PayPal.
        Basic parameters

        Example response

        {
            "Key": "CC4307C1575D43598577231F14XXXXXX",
            "Status": {
                "Code": {
                    "Code": 190,
                    "Description": "Success"
                },
                "SubCode": {
                    "Code": "P910",
                    "Description": "The PayPal referencetransaction is completed."
                },
                "DateTime": "2017-03-30T11:51:03"
            },
            "RequiredAction": null,
            "Services": [
                {
                    "Name": "paypal",
                    "Action": null,
                    "Parameters": [
                        {
                            "Name": "payerEmail",
                            "Value": "johnsmith@gmail.com"
                        },
                        {
                            "Name": "payerCountry",
                            "Value": "NL"
                        },
                        {
                            "Name": "payerStatus",
                            "Value": "unverified"
                        },
                        {
                            "Name": "payerFirstname",
                            "Value": "John"
                        },
                        {
                            "Name": "payerLastname",
                            "Value": "Smith"
                        }
                    ]
                }
            ],
            "CustomParameters": null,
            "AdditionalParameters": null,
            "RequestErrors": null,
            "Invoice": "testinvoice 1223",
            "ServiceCode": "paypal",
            "IsTest": true,
            "Currency": "EUR",
            "AmountDebit": 10,
            "TransactionType": "V014",
            "MutationType": 2,
            "RelatedTransactions": null,
            "ConsumerMessage": null,
            "Order": null,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": true,
            "CustomerName": "John Smith",
            "PayerHash": null,
            "PaymentKey": "00BF3EBA21064B2485D44538F7XXXXXX"
        }
        

        PayRecurrent push

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        payerStatusStringN/AN/AThe account status of the consumers PayPal account. Can be ‘Verified’ or ‘Unverified’
        payerEmailStringN/AN/AThe email address of the PayPal account of the consumer.
        payerCountryStringN/AN/AThe countrycode of the consumer (2-letter ISO country code, e.g. NL)
        payerfirstnameStringN/AN/AThe first name of the PayPal account of the consumer.
        payerlastnameStringN/AN/AThe last name of the PayPal account of the consumer.
        payertransactionidStringN/AN/AThe unique number given by PayPal.
        Basic parameters

        Example response

        {
          "Transaction": {
            "Key": "CC4307C1575D43598577231F14XXXXXX",
            "Invoice": "testinvoice 1223",
            "ServiceCode": "paypal",
            "Status": {
              "Code": {
                "Code": 190,
                "Description": "Success"
              },
              "SubCode": {
                "Code": "P910",
                "Description": "The PayPal referencetransaction is completed."
              },
              "DateTime": "2017-03-30T11:51:03"
            },
            "IsTest": true,
            "Order": null,
            "Currency": "EUR",
            "AmountDebit": 10,
            "TransactionType": "V014",
            "Services": [
              {
                "Name": "paypal",
                "Action": null,
                "Parameters": [
                  {
                    "Name": "payerEmail",
                    "Value": "johnsmith@gmail.com"
                  },
                  {
                    "Name": "payerCountry",
                    "Value": "NL"
                  },
                  {
                    "Name": "payerStatus",
                    "Value": "unverified"
                  },
                  {
                    "Name": "payerFirstname",
                    "Value": "John"
                  },
                  {
                    "Name": "payerLastname",
                    "Value": "Smith"
                  }
                ],
                "VersionAsProperty": 1
              }
            ],
            "CustomParameters": null,
            "AdditionalParameters": null,
            "MutationType": 2,
            "RelatedTransactions": null,
            "IsCancelable": false,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": true,
            "CustomerName": "John Smith",
            "PayerHash": null,
            "PaymentKey": "00BF3EBA21064B2485D44538F7XXXXXX"
          }
        }
        

        ExtraInfo

        The ExtraInfo can be sent to our API in addition to the Pay action. This action cannot be used as a standalone action.

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        NameStringYesN/AThe name of the consumer. It can be 32 characters max.
        Street1StringYesN/AThe first line of the shipping address (typically street and house number). It can be 100 characters max.
        Street2StringYesN/AThe second line of the shipping address (optional). It can be 100 characters max.
        CityNameStringYesN/ACity of the shipping address. It can be 40 characters max.
        StateOrProvinceStringYesN/AState or province code of the shipping address. These can be found on the following PayPal page: https://developer.paypal.com/docs/api/reference/state-codes/. Note that it is only required for the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA.
        PostalCodeStringYesNoPostalCode / ZipCode of the shipping address. It can be 20 characters max.
        CountryStringYesNoCountrycode of the shipping address (2 letter country code eg. NL or FR). These can be found on the following PayPal page: https://developer.paypal.com/docs/api/reference/country-codes/
        NoShippingStringNoNoHow to handle the shipping address: 0: PayPal displays the shipping address on the PayPal pages 1: PayPal does not display shipping address fields whatsoever. 2: If you do not pass the shipping address, PayPal obtains it from the buyer’s account profile. (default, recommended when trying to obtain seller protection). This should be an integer.
        AddressOverrideStringYesNoWhether or not the consumer is allowed to choose his shipping address in the Paypal pages. True: Shipping address sent by merchant overrides shipping address on file at PayPal False: Shipping address sent by merchant does not override shipping address on file at PayPal allowing the consumer to select a different address in the PayPal pages. If override=false, the address as selected by the consumer in the PayPal pages is returned as output parameters. This should be a boolean value.
        Basic parameters

        Example request

        {
          "Currency": "EUR",
          "AmountDebit": 10.00,
          "Invoice": "testinvoice 123a",
          "Services": {
            "ServiceList": [
              {
                "Name": "paypal",
                "Action": "Pay,ExtraInfo",
                "Parameters": [
                  {
                    "Name": "Name",
                    "Value": "John Smith"
                  },
                  {
                    "Name": "Street1",
                    "Value": "Hoofstraat 90"
                  },
                  {
                    "Name": "Street2",
                    "Value": ""
                  },
                  {
                    "Name": "CityName",
                    "Value": "Heerenveen"
                  },
                  {
                    "Name": "StateOrProvince",
                    "Value": ""
                  },
                  {
                    "Name": "PostalCode",
                    "Value": "8441AB"
                  },
                  {
                    "Name": "Country",
                    "Value": "NL"
                  },
                  {
                    "Name": "Phone",
                    "Value": ""
                  },
                  {
                    "Name": "NoShipping",
                    "Value": ""
                  },
                  {
                    "Name": "AddressOverride",
                    "Value": "true"
                  }
                ]
              }
            ]
          }
        }
        

        ExtraInfo response

        If the request has a valid structure and a valid signature, a transaction will be created in the Payment Engine and a response will be returned. In this case, an additional action is required before the transaction can be completed. The customer needs to be redirected to the payment environment through the returned redirect URL.

        Parameters

        Basic parameters

        Example response

        {
          "Key": "1DD4EBFF828D462F8749B10A59XXXXXX",
          "Status": {
            "Code": {
              "Code": 791,
              "Description": "Pending processing"
            },
            "SubCode": {
              "Code": "S002",
              "Description": "An additional action is required: PayPal ExpressCheckout"
            },
            "DateTime": "2017-05-18T10:09:24"
          },
          "RequiredAction": {
            "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=B2EE3176335A4C259CB051A543XXXXXX",
            "RequestedInformation": null,
            "PayRemainderDetails": null,
            "Name": "Redirect",
            "TypeDeprecated": 0
          },
          "Services": null,
          "CustomParameters": null,
          "AdditionalParameters": null,
          "RequestErrors": null,
          "Invoice": "testinvoice 123a",
          "ServiceCode": "paypal",
          "IsTest": true,
          "Currency": "EUR",
          "AmountDebit": 10.0,
          "TransactionType": "V010",
          "MutationType": 2,
          "RelatedTransactions": null,
          "ConsumerMessage": null,
          "Order": null,
          "IssuingCountry": null,
          "StartRecurrent": false,
          "Recurring": false,
          "CustomerName": null,
          "PayerHash": null,
          "PaymentKey": "3D1CC82B47B24598BFB510B1DEXXXXXX"
        }
        

        ExtraInfo push

        Parameters

        Service specific parameters

        ParameterTypeRequiredRecommendedDescription
        SelectedNameStringYesN/AThe name of the consumer. It can be 32 characters max.
        SelectedStreet1StringYesN/AThe first line of the shipping address (typically street and house number). It can be 100 characters max.
        SelectedStreet2StringYesN/AThe second line of the shipping address (optional). It can be 100 characters max.
        SelectedCityNameStringYesN/ACity of the shipping address. It can be 40 characters max.
        SelectedStateOrProvinceStringYesN/AState or province code of the shipping address. These can be found on the following PayPal page: https://developer.paypal.com/docs/api/reference/state-codes/. Note that it is only required for the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand, USA.
        SelectedPostalCodeStringYesNoPostalCode / ZipCode of the shipping address. It can be 20 characters max.
        SelectedCountryStringYesNoCountrycode of the shipping address (2 letter country code eg. NL or FR). These can be found on the following PayPal page: https://developer.paypal.com/docs/api/reference/country-codes/
        AdressStatusStringN/AN/AThe status of the address, Can be either None, Confirmed or Unconfimed.
        ProtectionEligibilityStringN/AN/AWhether or not you are eligible for seller protection. Can be: Eligible – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payments and Item Not Received. PartiallyEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received. Ineligible – Merchant is not protected under the Seller Protection Policy.
        ProtectionEligibilityTypeStringN/AThe type of protection you are eligible to. Can be: Eligible – Merchant is protected by PayPal's Seller Protection Policy for both Unauthorized Payment and Item Not Received ItemNotReceivedEligible – Merchant is protected by PayPal's Seller Protection Policy for Item Not Received UnauthorizedPaymentEligible – Merchant is protected by PayPal's Seller Protection Policy for Unauthorized Payment Ineligible – Merchant is not protected under the Seller Protection Policy.
        Basic parameters

        Example push

        {
          "Transaction": {
            "Key": "1DD4EBFF828D462F8749B10A59XXXXXX",
            "Invoice": "testinvoice 123a",
            "ServiceCode": "paypal",
            "Status": {
              "Code": {
                "Code": 190,
                "Description": "Success"
              },
              "SubCode": {
                "Code": "P904",
                "Description": "The PayPal payment has been completed."
              },
              "DateTime": "2017-05-18T10:16:39"
            },
            "IsTest": true,
            "Order": null,
            "Currency": "EUR",
            "AmountDebit": 10,
            "TransactionType": "V010",
            "Services": [
              {
                "Name": "paypal",
                "Action": null,
                "Parameters": [
                  {
                    "Name": "AddressStatus",
                    "Value": "Confirmed"
                  },
                  {
                    "Name": "payerEmail",
                    "Value": "johnsmith@gmail.com"
                  },
                  {
                    "Name": "payerCountry",
                    "Value": "NL"
                  },
                  {
                    "Name": "payerStatus",
                    "Value": "unverified"
                  },
                  {
                    "Name": "payerFirstname",
                    "Value": John"
                  },
                  {
                    "Name": "payerLastname",
                    "Value": "Tester"
                  },
                  {
                    "Name": "ProtectionEligibility",
                    "Value": "Eligible"
                  },
                  {
                    "Name": "ProtectionEligibilityType",
                    "Value": "ItemNotReceivedEligible,UnauthorizedPaymentEligible"
                  },
                  {
                    "Name": "paypalTransactionID",
                    "Value": "5XF2719921258562Y"
                  }
                ],
                "VersionAsProperty": 1
              }
            ],
            "CustomParameters": null,
            "AdditionalParameters": null,
            "MutationType": 2,
            "RelatedTransactions": null,
            "IsCancelable": false,
            "IssuingCountry": null,
            "StartRecurrent": false,
            "Recurring": false,
            "CustomerName": "John Smith",
            "PayerHash": null,
            "PaymentKey": "3D1CC82B47B24598BFB510B1DEXXXXXX"
          }
        }
        |

        Was this article helpful?