Integrate Reference Transactions with Transaction Risk

PayPal partners and merchants can Set transaction context to send additional data about a customer to PayPal so that PayPal can complete a pre-transaction risk management evaluation before PayPal processes the customer transaction.

You can integrate the REST Transaction Risk API Set transaction context method with Express Checkout reference transactions.

A reference transaction is a financial transaction from which you can initiate subsequent transactions. For example, a customer makes a purchase on a merchant's site. To use this purchase as a reference transaction, use the ID of the purchase as the reference transaction ID in subsequent transactions.

Integration process flow

This sequence diagram illustrates the integration process flow:

Integration steps

Set up your development environment

Before you can integrate Reference Transactions with Transaction Risk, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Reference Transactions with Transaction Risk.

Set the transaction context

To integrate Transaction Risk API methods with Express Checkout reference transactions, you must make a Set transaction context call before you make the initial classic DoReferenceTransaction reference transaction call. You pass a merchant_id and tracking_id in the set the transaction context call.

Use the token value from the response in the previous step as the tracking_id parameter and use the merchant ID from PayPal business account Profile page as the merchant_id parameter in the request:

curl -v -X PUT https://api-m.sandbox.paypal.com/v1/risk/transaction-contexts/<var>merchant_id</var>/<var>tracking_id</var> \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <var>Access-Token</var> \
  -d '{
  "additional_data": [
  {
    "key": "test1",
    "value": "abc"
  },
  {
    "key": "test2",
    "value": "aaa"
  }]
}'

The initial Express Checkout operation returns a token that you use as the tracking_id value in the set the transaction context call.

Set up billing agreement

Before you can call a reference transaction, make a classic SetExpressCheckout call to set up a billing agreement.

Pass a billing agreement type and billing agreement description in the request. For example, L_BILLINGTYPE0=MerchantInitiatedBilling and L_BILLINGAGREEMENTDESCRIPTION0=ClubUsage. Specify a purchase amount of 0.

Endpoint URL: https://api-3t.sandbox.paypal.com/nvp HTTP method: POST POST data: USER=&PWD=&SIGNATURE=&METHOD=SetExpressCheckout &VERSION=86 &PAYMENTREQUEST_0_PAYMENTACTION=AUTHORIZATION     # Payment authorization &PAYMENTREQUEST_0_AMT=0                           # The amount authorized is 0 &PAYMENTREQUEST_0_CURRENCYCODE=USD                # The currency. For example, US dollars &L_BILLINGTYPE0=MerchantInitiatedBilling          # The type of billing agreement &L_BILLINGAGREEMENTDESCRIPTION0=ClubUsage         # The description of the billing agreement &cancelUrl=https://example.com/cancel             # For use if the consumer decides not to proceed with payment &returnUrl=https://example.com/success            # For use if the consumer proceeds with payment

The SetExpressCheckout response returns a token that you use in subsequent steps.

TOKEN=EC%2d2B984685J43051234 &ACK=Success

Redirect the customer to PayPal for authorization

Use the access token in the PayPal authorization URL:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=Token If the customer does not provide authorization, the customer is redirected to the cancel URL that you specified in the SetExpressCheckout call, so you can provide a way to re-initiate checkout.

Set up billing agreement without a purchase

Call CreateBillingAgreement in place of DoExpressCheckoutPayment to enable a customer to set up a billing agreement before making a payment.

If the customer authorizes the payment, the customer is redirected to the return URL that you specified in the SetExpressCheckout call. The return URL is appended with the same token that you used in the redirect step.

Call CreateBillingAgreement with this URL-decoded token:

Endpoint URL: https://api-3t.sandbox.paypal.com/nvp HTTP method: POST POST data: USER=merchant_user_name&PWD=merchant_password&SIGNATURE=merchant_signature_value&METHOD=CreateBillingAgreement &VERSION=86 &TOKEN=tokenValue The CreateBillingAgreement response includes a billing agreement ID for use in the capture authorized payments step.

BILLINGAGREEMENTID=B%2d7FB31251F28061234 &ACK=Success

Capture authorized payment

In the capture payment operation of the reference transaction call, pass the tracking_id that you used in the set the transaction context call in the MerchantSessionId parameter.

PayPal recognizes that the reference transaction token matches a token in a set the transaction context call. PayPal uses the transaction data context to complete additional risk management before it processes additional payments.

For future payments, make a DoReferenceTransaction call. In the REFERENCEID parameter, specify the URL- decoded billing agreement ID from the BILLINGAGREEMENTID output field from the set up billing agreement step.

Because this call charges the customer's PayPal account, specify a payment amount and related fields, as follows. For field descriptions, see the DoReferenceTransaction operation. In the MerchantSessionId parameter, specify the unique tracking_id value that you used in the set the transaction context call.

Endpoint URL: https://api-3t.sandbox.paypal.com/nvp HTTP method: POST POST data: USER=&PWD=&SIGNATURE=&METHOD=DoReferenceTransaction &VERSION=86 &AMT=50                          # The amount the customer will pay in a payment period &CURRENCYCODE=USD                # The currency, such as US dollars &PAYMENTACTION=SALE              # The type of payment &REFERENCEID=B-7FB31251F28061234 # Billing agreement ID received in the CreateBillingAgreement call &MerchantSessionId= # Unique tracking ID used in the set transaction context call

The response includes the billing agreement ID and transaction information:

BILLINGAGREEMENTID=B%2d7FB31251F28061234 &ACK=Success &TRANSACTIONID=98A13946GS4491234 &TRANSACTIONTYPE=merchtpmt &PAYMENTTYPE=instant &AMT=50%2e00 &PAYMENTSTATUS=Completed

Additional information

For information about classic payment calls, see: