Skip to content

Instantly share code, notes, and snippets.

@wilbertverayin

wilbertverayin/paypal_batch_payout.md

Last active October 29, 2015 04:33
Show Gist options
  • Save wilbertverayin/d4543c02e56ad99996f3 to your computer and use it in GitHub Desktop.
Save wilbertverayin/d4543c02e56ad99996f3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
paypal_batch_payout.md

Paypal Batch Payout

Documentation

Documentation for Batch Payout https://developer.paypal.com/docs/integration/direct/payouts-overview/

Usage

https://developer.paypal.com/docs/integration/direct/create-batch-payout/

Sample Request
curl -v https://api.sandbox.paypal.com/v1/payments/payouts/ \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
    "sender_batch_header": {
        "sender_batch_id": "2014021801",
        "email_subject": "You have a Payout!",
        "recipient_type": "EMAIL"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": "1.0",
                "currency": "USD"
            },
            "note": "Thanks for your patronage!",
            "sender_item_id": "201403140001",
            "receiver": "[email protected]"
        }
    ]
}'
Sample Response
{
  "batch_header": {
    "payout_batch_id": "CDZEC5MJ8R5HY",
    "batch_status": "SUCCESS",
    "time_created": "2014-46-14T06:46:22Z",
    "time_completed": "2014-46-14T06:46:23Z",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a Payout!"
    },
    "amount": {
      "currency": "USD",
      "value": "1.0"
    },
    "fees": {
      "currency": "USD",
      "value": "0.02"
    }
  },
  "items": [
    {
      "payout_item_id": "VHBFGN95AWV82",
      "transaction_id": "0728664497487461D",
      "transaction_status": "SUCCESS",
      "payout_item_fee": {
        "currency": "USD",
        "value": "0.02"
      },
      "payout_batch_id": "CDZEC5MJ8R5HY",
      "payout_item": {
        "amount": {
          "currency": "USD",
          "value": "1.0"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]",
        "recipient_type": "EMAIL",
        "sender_item_id": "201403140001"
      },
      "time_processed": "2014-46-14T06:46:23Z",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/VHBFGN95AWV82",
          "rel": "item",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/payouts/CDZEC5MJ8R5HY",
      "rel": "self",
      "method": "GET"
    }
  ]
}
Fees

The sender pays Payouts fees at the time of the transaction. US sent domestic Payouts sent over the Payouts API are priced at $0.25 USD flat per transaction. Canadian sent domestic Payouts are priced at $0.32 CAD flat per transaction. US and Canadian sent cross border Payouts are priced just like Mass Payments (2% of each transaction, capped at $20 USD, and $23 CAD respectively). Payouts sent from any other country are priced just like Mass Payments.

Reporting

Reviewing Batch Payout https://developer.paypal.com/docs/api/#get-the-status-of-a-batch-payout

Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/payments/payouts/12345678 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer <Access-Token>"
-d '{}'

######Sample Response

{
  "batch_header": {
    "payout_batch_id": "12345678",
    "batch_status": "PROCESSING",
    "sender_batch_id": "2014021801",
    "time_created": "2014-01-27T10:17:00Z",
    "time_completed": "2014-01-27T11:17:39.00Z",
    "sender_batch_header": {
      "sender_batch_id": "2014021801",
      "email_subject": "You have a Payout!"
    },
    "amount": {
      "value": "435.85",
      "currency": "USD"
    },
    "fees": {
      "value": "5.84",
      "currency": "USD"
    }
  },
  "items": [
    {
      "payout_item_id": "452176",
      "transaction_id": "434176",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021887",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "65.24",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]",
        "payouts_item_id": "1421388",
        "sender_item_id": "14Feb_978"
      },
      "time_created": "2014-01-27T10:17:00:00Z",
      "time_processed": "2014-01-27T10:18:32Z"
    },
    {
      "payout_item_id": "452123",
      "transaction_id": "434123",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021802",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]",
        "payouts_item_id": "1421345",
        "sender_item_id": "14Feb_321"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:18:15Z"
    },
    {
      "payout_item_id": "452323",
      "transaction_id": "434543",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021802",
      "payout_item_fee": {
        "currency": "USD",
        "value": "1.00"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "59.87",
          "currency": "EUR"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]",
        "payouts_item_id": "1421355",
        "sender_item_id": "14Feb_239"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:15Z"
    },
    {
      "payout_item_id": "452350",
      "transaction_id": "434543",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item_fee": {
        "value": "USD",
        "currency": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "19.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]@gmail.com",
        "payouts_item_id": "1421332",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:25Z"
    },
    {
      "payout_item_id": "452345",
      "transaction_id": "4345",
      "transaction_status": "SUCCESS",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item_fee": {
        "currency": "USD",
        "value": "0.75"
      },
      "payout_item": {
        "recipient_type": "EMAIL",
        "amount": {
          "value": "9.87",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "[email protected]",
        "payouts_item_id": "1421342",
        "sender_item_id": "14Feb_234"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:37Z"
    },
    {
      "payout_item_id": "4782902",
      "transaction_id": "6456456",
      "transaction_status": "SUCCESS",
      "payout_item_fee": {
        "currency": "USD",
        "value": "2.35"
      },
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "112.34",
          "currency": "EUR"
        },
        "note": "Thanks for your support!",
        "receiver": "91-734-234-1234",
        "payouts_item_id": "1421343",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:52Z"
    },
    {
      "payout_item_id": "4782902",
      "transaction_id": "",
      "transaction_status": "PROCESSING",
      "payout_batch_id": "12345678",
      "sender_batch_id": "2014021801",
      "payout_item": {
        "recipient_type": "PHONE",
        "amount": {
          "value": "5.32",
          "currency": "USD"
        },
        "note": "Thanks for your patronage!",
        "receiver": "408X234-1234",
        "payouts_item_id": "1421344",
        "sender_item_id": "14Feb_235"
      },
      "time_created": "2014-01-27T10:17:00Z",
      "time_processed": "2014-01-27T10:17:41Z"
    }
  ]
}
Payment Statuses
  • SUCCESS - The item has been successfully processed.
  • DENIED - The item has been denied payment.
  • PENDING - The item is awaiting payment.
  • PROCESSING - The item is being processed.
  • FAILED - Processing failed for the item.
  • UNCLAIMED - The item is unclaimed. If the item is not claimed within 30 days, the funds will be returned to the sender.
  • RETURNED - The item is returned. The funds are returned if the recipient hasn’t claimed them in 30 days.
  • ONHOLD - The item is on hold.
  • BLOCKED - The item is blocked.
  • CANCELLED - It is not possible for the CANCELLED state to occur if the sender is solely using the API to send Payouts. This status is an edge-case if a sender uses both the MassPay web upload and the Payouts API, cancels the web upload, and then uses the API to find the batch/items. In this case, CANCELLED status is possible.
/* Copyright 2015 PayPal

Create a batch payout, by default in asynchronous mode.

*/
"use strict";
var paypal = require('../../');
require('../configure');

var sender_batch_id = Math.random().toString(36).substring(9);
console.log(sender_batch_id);
var create_payout_json = {
    "sender_batch_header": {
        "sender_batch_id": sender_batch_id,
        "email_subject": "You have a payment"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.10,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        },
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.20,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        },
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.30,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        }
    ]
};

paypal.payout.create(create_payout_json, function (error, payout) {
    if (error) {
        console.log(error.response);
        throw error;
    } else {
        console.log("Create Payout Response");
        console.log(payout);
    }
});
/* Copyright 2015 PayPal

Create a batch payout, by default in asynchronous mode.

*/
"use strict";
var paypal = require('../../');
require('../configure');

var sender_batch_id = Math.random().toString(36).substring(9);
console.log(sender_batch_id);
var create_payout_json = {
    "sender_batch_header": {
        "sender_batch_id": sender_batch_id,
        "email_subject": "You have a payment"
    },
    "items": [
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.10,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        },
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.20,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        },
        {
            "recipient_type": "EMAIL",
            "amount": {
                "value": 0.30,
                "currency": "USD"
            },
            "receiver": "[email protected]",
            "note": "payment sent to [email protected]",
            "sender_item_id": "[email protected]"
        }
    ]
};

paypal.payout.create(create_payout_json, function (error, payout) {
    if (error) {
        console.log(error.response);
        throw error;
    } else {
        console.log("Create Payout Response");
        console.log(payout);
    }
});
{
    batch_header: {
        payout_batch_id: 'PBU2RFFPH3LZY',
        batch_status: 'PENDING',
        sender_batch_header: {
            email_subject: 'Youhaveapayment',
            sender_batch_id: '2k2o6r'
        }
    },
    links: [
        {
            href: 'https: //api.sandbox.paypal.com/v1/payments/payouts/PBU2RFFPH3LZY',
            rel: 'self',
            method: 'GET'
        }
    ],
    httpStatusCode: 201
}

Retrieving transactions from a batch payout called mass pay

/* Copyright 2015 PayPal */
"use strict";

var paypal = require('../../');
require('../configure');

var payoutId = "PBU2RFFPH3LZY";

paypal.payout.get(payoutId, function (error, payout) {
    if (error) {
        console.log(error);
        throw error;
    } else {
        console.log("Get Payout Response");
        console.log(JSON.stringify(payout));
    }
});

Result

{
    "batch_header": {
        "payout_batch_id": "PBU2RFFPH3LZY",
        "batch_status": "SUCCESS",
        "time_created": "2015-10-28T08:21:27Z",
        "time_completed": "2015-10-28T08:21:53Z",
        "sender_batch_header": {
            "email_subject": "You have a payment",
            "sender_batch_id": "2k2o6r"
        },
        "amount": {
            "currency": "USD",
            "value": "0.6"
        },
        "fees": {
            "currency": "USD",
            "value": "0.75"
        }
    },
    "items": [
        {
            "payout_item_id": "GEZFDMBP86PBS",
            "transaction_id": "2UF38416WG641032S",
            "transaction_status": "SUCCESS",
            "payout_item_fee": {
                "currency": "USD",
                "value": "0.25"
            },
            "payout_batch_id": "PBU2RFFPH3LZY",
            "payout_item": {
                "amount": {
                    "currency": "USD",
                    "value": "0.1"
                },
                "note": "payment sent to [email protected]",
                "receiver": "[email protected]",
                "recipient_type": "EMAIL",
                "sender_item_id": "[email protected]"
            },
            "time_processed": "2015-10-28T08:21:45Z",
            "links": [
                {
                    "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/GEZFDMBP86PBS",
                    "rel": "item",
                    "method": "GET"
                }
            ]
        },
        {
            "payout_item_id": "8Q7VESRTST88G",
            "transaction_id": "0JE18235XX865291G",
            "transaction_status": "SUCCESS",
            "payout_item_fee": {
                "currency": "USD",
                "value": "0.25"
            },
            "payout_batch_id": "PBU2RFFPH3LZY",
            "payout_item": {
                "amount": {
                    "currency": "USD",
                    "value": "0.2"
                },
                "note": "payment sent to [email protected]",
                "receiver": "[email protected]",
                "recipient_type": "EMAIL",
                "sender_item_id": "[email protected]"
            },
            "time_processed": "2015-10-28T08:21:45Z",
            "links": [
                {
                    "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/8Q7VESRTST88G",
                    "rel": "item",
                    "method": "GET"
                }
            ]
        },
        {
            "payout_item_id": "DP6W9QZZLDLEY",
            "transaction_id": "51T237094M966414R",
            "transaction_status": "SUCCESS",
            "payout_item_fee": {
                "currency": "USD",
                "value": "0.25"
            },
            "payout_batch_id": "PBU2RFFPH3LZY",
            "payout_item": {
                "amount": {
                    "currency": "USD",
                    "value": "0.3"
                },
                "note": "payment sent to [email protected]",
                "receiver": "[email protected]",
                "recipient_type": "EMAIL",
                "sender_item_id": "[email protected]"
            },
            "time_processed": "2015-10-28T08:21:45Z",
            "links": [
                {
                    "href": "https://api.sandbox.paypal.com/v1/payments/payouts-item/DP6W9QZZLDLEY",
                    "rel": "item",
                    "method": "GET"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "https://api.sandbox.paypal.com/v1/payments/payouts/PBU2RFFPH3LZY",
            "rel": "self",
            "method": "GET"
        }
    ],
    "httpStatusCode": 200
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment