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:

1. Establishing a legal entity (finishing the KYB procedure)

2. Open A Wallet (through the app)

Open Wallet

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.

The wallet ID can be obtained using the Get Wallets List API or from the application (under the View Wallet).

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.

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.

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.

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

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.

Payment instructions can be obtained using the Get Payment Details API (if the payment ID is known) or by the Get Payments List API.

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
   }
}