Real-Life Scenarios
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.
Request Example
POST/token
{
"api_key": "82725488-22bf-40d1-ace6-9ea6ee42f870",
"client_secret": "MySecret!",
"expiration": 100001,
"token_name": "testEXP13"
}Response Example
{
"valid_until": "2024-07-17T15:42Z",
"token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJBUElLRVkwIiwiYXBpX3Rva2VuX2lkIjoiNDIwNjJiMWMtOWRmYy00NzI2LTllYTAtYmM4MGI0MzcwOWJkIiwiYWxnIjoiUlMyNTYifQ.eyJpYXQiOjE3MjExMzA5NzMsImV4cCI6MTcyMTIzMDk3NCwic3ViIjoiYWNjZXNzIiwidXNlciI6eyJpZCI6IjgyNzI1NDg4LTIyYmYtNDBkMS1hY2U2LTllYTZlZTQyZjg3MCIsImVtYWlsIjoiZXlhbDEubmV0QGdtYWlsLmNvbSIsIm93bmVyIjp7ImlkIjoiMjAxMDAwIiwib3duZXJUeXBlIjoib3JnX2lkIn19fQ.YCV6m7jGAJBLY8HDtMK-1UkgM_DNS9JKLMojUNstQGoR7ZjMxcQ3aNb3HvvQpq-OaEAy99TjpI2XB_b7zu87J4AvPuHgM9rsHlZagwQt0M6LK0PsN7K8d8RKbPuaXsZvc3SQ4t0HqxfrD8nYC7C63ImPMsEYzvOvLYSoYXwmQ74vFzCXVi3vhWwth-07JhVAp8-S46zGqBNODhMkUPBnUXBkI6KL3A_ElKwaH3YI4ZFsCOKJu0DnZJvPUDqsJRz9l0Hics058eiCOqqs4ODDegHSLGrQyUsZVMyJ_InI9LSNtaw6dal1i4_3zPUAE04aXonMcZDt_Bv9fjoUoqf9Ew",
"token_name": "testEXP13"
}2. Create a Payment Group
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.
Request Example
POST /payments/groups
{
"description": "Demo Group",
"wallet": "f6b2776d-53f4-404e-a690-c3766a91d43a",
"name": "February USD cycle",
"user_tags":{
"cycle":"2024-02"
}
}Response Example
{
"type": "group",
"id": "b48c3f38-9278-41a3-b101-444f20fce982",
"description": "Demo Group",
"wallet": "f6b2776d-53f4-404e-a690-c3766a91d43a",
"name": "February USD cycle",
"user_tags": {
"cycle":"2024-02"
}
}3. Create Beneficiary
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.
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.
Request Example
POST /payments/payments
{
"source": {
"id": "7fb54ffb-0f1e-4df5-b81c-7046d2987df0",
"type": "group"
},
"target": {
"id": "GHXY5QuJRxSIrfkfcaBzUg",
"type": "contact"
},
"execution": {
"date": "2024-03-02T09:09:51.508859936Z",
"type": "LAND",
"margin": 4
},
"amount": {
"amount": 1000,
"type": "LAND",
"currency": "USD"
},
"description": "Remittance instruction",
"id": "66666",
"signature": "<string>",
"purpose": "SALA",
"approved": true,
"final": {
"is_final": true,
"expected": "2024-03-02T09:09:51.508859936Z"
},
"attachments": [
{
"url": "https://www.papayaglobal.com/",
"title": "papayaglobal",
"attachment_id": "123"
},
{
"url": "https://docs.papayaglobal.com",
"title": "Global payments API",
"attachment_id": "456"
}
],
"user_tags": {
"enimb5": "demo test payment"
}
}Response Example
{
"id": "66666",
"description": "Remittance instruction",
"purpose": "SALA",
"source": {
"id": "7fb54ffb-0f1e-4df5-b81c-7046d2987df0",
"type": "group"
},
"target": {
"type": "contact",
"id": "GHXY5QuJRxSIrfkfcaBzUg"
},
"info": {
"funding": {
"amount": 0
},
"status": "PENDING",
"credit": {
"currency": "USD",
"amount": 1000
},
"fees": 0
},
"amount": {
"type": "LAND",
"amount": 1000,
"currency": "USD"
},
"execution": {
"date": "2024-03-02T09:09:51Z",
"margin": 4
},
"final": {
"is_final": true
},
"attachments": [
{
"attachment_id": "123",
"title": "papayaglobal",
"url": "https://www.papayaglobal.com/"
},
{
"attachment_id": "456",
"title": "Global payments API",
"url": "https://docs.papayaglobal.com"
}
],
"approved": true,
"user_tags": {
"enimb5": "demo test payment"
}
}5. Check Wallet Balance
Retrieve wallet details and verify the balance associated with the wallet ID. If there are insufficient funds available, ensure you top up your wallet.
Request Example
GET /payments/wallets/?id=f6b2776d-53f4-404e-a690-c3766a91d43a
Response Example
{
"items": [
{
"id": "f6b2776d-53f4-404e-a690-c3766a91d43a",
"currency": "USD",
"name": "Demo USD Wallet",
"type": "wallet",
"owner": "entity://business/customer/demo:standalone:1709197789/legal/0d65c5cd-4896-45b9-b268-c431b82605af",
"funding": {
"name": "RONKIֹ LTD CMA - EUR",
"country": "GB",
"account_number": "UKNWBK60161529100024",
"bic": "CHASGB2L",
"iban": "UKNWBK60161529100024"
},
"balance": 120000,
"user_tags": {
"department": "sales"
},
"state": "ACTIVE"
}
],
"paging": {
"skip": 0,
"take": 0
}
}6. Approve Payment Instruction
Review the payment instruction details and approve the transaction by indicating the IDs of the payment.
Request Example
PATCH /payments/payments/approve?id=1573c466-53ba-46e7-a7f2-b6d49c79716b
Response Examples
{
"items": [
{
"result": "Approved Successfully",
"id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
"type": "payment"
}
]
} 7. Check Payment Status
Obtain payment information and check the payment status by providing the payment ID.
Request Example
GET /payments/payments/id=1573c466-53ba-46e7-a7f2-b6d49c79716b
Response Examples
{
"items": [
{
"id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
"description": "Uk test in DM",
"purpose": "SALA",
"source": {
"id": "01f5d-844c-4487-82d1-fc0faec0ab6d",
"type": "group"
},
"target": {
"type": "contact",
"id": "8va9KENJSD2BbafQgDEecA"
},
"info": {
"funding": {
"date": "2024-07-08T05:00:00Z",
"currency": "GBP",
"amount": 834.32075
},
"status": "PENDING",
"credit": {
"currency": "USD",
"amount": 1000
},
"rate": 1.21600101,
"fees": 11.95302
},
"amount": {
"type": "LAND",
"amount": 1000
},
"execution": {
"date": "2024-07-10T08:00:00Z"
},
"final": {
"is_final": true,
"expected": "2024-07-08T05:00:00Z"
},
"attachemnts": [],
"approved": true,
"user_tags": {}
}
],
"paging": {
"take": 50,
"skip": 0
}
}
Last updated