How do I get started with PayPal APIs and SDKs?
An Application Programming Interface (API) is a safe gateway to use a company’s code or tool to accomplish a task. Using an API, you can get the local weather, check incoming flights with a certain airline, create a Google Map, or create a payment with PayPal.
Requests and responses
Each API has a request and a response.
- The request is your application’s message to the API. It includes parameters such as the transaction amount, shipping address, tax amount, item description, or item quantity.
- The response is the API’s message back to your application. Once you've built your API request, you should receive a response within a few seconds.
Request success and failure
If the request is received correctly, with no timeouts, you receive a response. Sometimes, though, this exchange fails; this is called a timeout. Timeouts can result when either the sending server or the receiving server encounters problems such as a power failure or code glitch.
For PayPal, each API response will have an ACK, or acknowledgment of “Success” or “Failure.”
- If the ACK reports success, you get detailed information about your transaction.
- If the ACK reports failure, you get an error code, a short message, and a long message. PayPal API has compiled a complete listing of error codes.
Issues with multiple API calls
Often, you must make multiple API calls to have one successful transaction. For example, the Express Checkout product requires two or three API method calls to complete a transaction.
- The SetExpressCheckout method sets up the transaction with all required information, and it can even change the look of the checkout page. However, the transaction is only set up; it's not complete yet.
- The API must send a call to DoExpressCheckoutPayment to complete the payment.
An API request often fails because an API didn't get the expected information, such as the correct total, or the shipping data when a shipping address is requested elsewhere.
Sometimes an API request expects information from another API request. For instance, a SetExpressCheckout response includes a token that should be used in DoExpressCheckoutPayment. If this token isn't used, the API won't work and will return a failure.
A Software Development Kit (SDK) is a pre-built set of functions that are language-specific (for example, PHP, ASP or Ruby) and do a lot of the heavy lifting for you. Instead of having to write an API call and convert the parameters into a format that the API expects, a programmer can use an SDK, which has language-specific methods to do this.
Where can I find more information about PayPal APIs and SDKs?
PayPal offers classic APIs, such as Express Checkout, Mass Payments, Invoicing, and Button Manager, as well as REST APIs, Payflow APIs, and Braintree APIs. While each of these links provides a brief overview of the product, you can also reference these more detailed development and integration guides.
See a demo and download code samples on the PayPal Demo Portal.
Which API or SDK option is right for me?
Which API you choose is up to you and your needs. Here's a short list of each product's features:
Express Checkout - This popular PayPal API is used for:
- Basic one-time payments.
- Authorization & capture payments.
- Order/authorization/capture payments.
- Reference transactions.
- Parallel payments.
- Recurring Payments.
- Search and retrieval of payment information.
- Subscriptions with a free trial period.
Mass Payments - This API allows a merchant to make batched payments in a few hours, giving recipients instant access to funds. It’s used for:
- Affiliate commissions.
- Customer rebates, prizes, and incentives.
- Pay-to-surf rewards.
- Employee benefits.
- Survey incentives.
Payouts - This API sends multiple individual payouts in one API call to an email address or US mobile phone number.
Invoicing - This API is used to:
- Send invoices to customers automatically.
- Automate accounts receivable and track payments more easily.
- Present invoices with your company logo, detailed business information, address, itemized sales data, discounts, shipping costs, tax, and more.
- Record invoices that customers pay using cash or check.
- Search invoices based on payment status, payee, and more.
Button Manager - This API automates button creation, similar to creating single buttons within the PayPal website.
REST API - The REST API is used to:
- Accept payment.
- Accept credit cards.
- Accept payments at a later date.
- Create and process orders.
- Process refunds.
- Look up payment details.
- Create test payments.
- Create billing plans and billing agreements.
Payflow - This API, which requires a monthly fee, lets you:
- Accept credit cards directly on your site.
- Send payment details to PayPal or host a PayPal page within your own site and avoid PCI compliance requirements. PayPal will handle PCI compliance for you.
- Handle debit and credit card payments, authorizations, captures, credit voids, advanced and basic fraud tools, PayPal payments, and PayPal Credit.
Braintree - The Braintree API is used for:
- Accepting payments via PayPal, Android Pay, Apple Pay, Venmo, Coinbase, and credit cards.
- Performing authorizations.
- Using advanced fraud tools.
- Marketplace payments (similar to Adaptive Payments).
- Recurring Billing.
- Managing customers and vault operations, as well as transaction data, voids, refunds, and validations.
To view demos and download code samples of Braintree and PayPal, visit the PayPal Demo Portal.