Real-life scenarios are depicted through an illustrative workflow overview.
Below is an illustrative workflow demonstrating how the Papaya Global Workforce Payments APIs function in real-world scenarios.
You need to transfer $7,000 in USD to an individual beneficiary in the United States. The payment will be sourced from the available balance in your USD wallet account.
Before you begin working with the API, you must first complete two required steps:
Establishing a legal entity (finishing the KYB procedure)
Open A Wallet (through the app)
1. Authentication
To get started, you must acquire an access token to access Papaya Global's Workforce Payments' various API endpoints. By utilizing your api_key and client_secret, you can make a request to the Token API endpoint. Upon successful authentication, you will receive an access token.
A group Allows the organization to consolidate and oversee payment requests effectively. A group is generated with a given wallet. Once created, you can supervise the group’s payment requests based on various criteria such as time, location, business unit, etc.
The wallet ID can be obtained using the Get Wallets List API or from the application (under the View Wallet).
Before making a payment, it is necessary to create a beneficiary resource. The beneficiary refers to the person or organization receiving the payment, and their bank details and preferred payment method are recorded. Once registered, the beneficiary ID can be used to send payment instructions.
Get insights on required fields and validation rules for beneficiary resource creation scenarios using the Get Schema Information API.
Request Example
POST /payments/beneficiaries
{"type":"INDIVIDUAL","country":"US","currency":"USD","user_tags": {"department":"R&D","cost_center":"US" },"entity": {"individual_first_name":"Smith","individual_last_name":"Johny","date_of_birth":"1970-01-01","address_line_1":"944 Fairfield Street","address_city":"Los Angeles","address_country":"US","address_country_subdivision":"CA","address_postal_code":"90210" },"bank_details": {"account_name":"John Smith","account_number":"1234567","bank_code":"123456789","bank_name":"Bank of America ","bank_identifier_code":"BOFAUS22XXX" }}
Response Example
{"type":"contact","id":"GHXY5QuJRxSIrfkfcaBzUg","currency":"USD","country":"US","bank_details": {"account_country":"US","account_name":"John Smith","account_number":"1234567","bank_code":"123456789","bank_identifier_code":"BOFAUS22XXX","bank_name":"Bank of America " },"entity": {"address_city":"Los Angeles","address_country":"US","address_country_subdivision":"CA","address_line_1":"944 Fairfield Street","address_postal_code":"90210","date_of_birth":"1970-01-01","individual_first_name":"Smith","individual_last_name":"Johny" },"user_tags": {"department":"R&D","cost_center":"US" },"active":false}
4. Create Payment Instruction
Creating payment Instructions will enable you to transfer funds to the registered beneficiary. The response will return all requisite details on the transaction.
Payment can be initiated by referencing the beneficiary ID generated through beneficiary resources. You can use the Get Beneficiaries List API to get the beneficiary ID.
Retrieve wallet details and verify the balance associated with the wallet ID. If there are insufficient funds available, ensure you top up your wallet.
The wallet ID can be obtained using the Get Wallets List API or the application (under the View Wallet).
Request Example
GET /payments/wallets/?id=f6b2776d-53f4-404e-a690-c3766a91d43a
