# Real-Life Scenarios

### Real-life scenarios are depicted through an illustrative workflow overview. <a href="#real-lifescenarios-illustrativeworkflowoverview-real-lifescenariosaredepictedthroughanillustrativewo" id="real-lifescenarios-illustrativeworkflowoverview-real-lifescenariosaredepictedthroughanillustrativewo"></a>

Below is an illustrative workflow demonstrating how the Papaya Global Workforce Payments APIs function in real-world scenarios.

{% hint style="success" %}
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.
{% endhint %}

#### Before you begin working with the API, you must first complete two required steps:  <a href="#real-lifescenarios-illustrativeworkflowoverview-1.authentication" id="real-lifescenarios-illustrativeworkflowoverview-1.authentication"></a>

1. Establishing a legal entity (finishing the KYB procedure)
2. Open A Wallet (through the app)

<figure><img src="/files/xTxKDiMYQWB3DGutl7pm" alt=""><figcaption><p>Open Wallet</p></figcaption></figure>

#### 1. Authentication <a href="#real-lifescenarios-illustrativeworkflowoverview-1.authentication" id="real-lifescenarios-illustrativeworkflowoverview-1.authentication"></a>

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

<mark style="color:green;">**`POST`**</mark>/token

```json
{
   "api_key": "82725488-22bf-40d1-ace6-9ea6ee42f870",
   "client_secret": "MySecret!",
   "token_name": "testEXP13"
}
```

**Response Example**

```json
{
   "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 href="#real-lifescenarios-illustrativeworkflowoverview-2.openawallet" id="real-lifescenarios-illustrativeworkflowoverview-2.openawallet"></a>

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.

{% hint style="info" %}
The wallet ID can be obtained using the Get Wallets List API or from the application (under the View Wallet).
{% endhint %}

**Request Example**

<mark style="color:green;">**`POST`**</mark> /payments/groups

```json
{
    "description": "Demo Group",
    "wallet": "f6b2776d-53f4-404e-a690-c3766a91d43a",
    "name": "February USD cycle",
    "user_tags":{
      "cycle":"2024-02"
    }
  }
```

**Response Example**

```json
{
  "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 <a href="#real-lifescenarios-illustrativeworkflowoverview-4.createbeneficiary" id="real-lifescenarios-illustrativeworkflowoverview-4.createbeneficiary"></a>

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.

{% hint style="info" %}
Get insights on required fields and validation rules for beneficiary resource creation scenarios using the Get Schema Information API.
{% endhint %}

**Request Example**

<mark style="color:green;">**`POST`**</mark> /payments/beneficiaries

```json
{
   "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**

```json
{
   "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 <a href="#real-lifescenarios-illustrativeworkflowoverview-5.createpaymentinstruction" id="real-lifescenarios-illustrativeworkflowoverview-5.createpaymentinstruction"></a>

Creating payment Instructions will enable you to transfer funds to the registered beneficiary. The response will return all requisite details on the transaction.

{% hint style="info" %}
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.
{% endhint %}

**Request Example**

<mark style="color:green;">**`POST`**</mark> /payments/payments

```json
{
   "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**

```json
{
   "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 <a href="#real-lifescenarios-illustrativeworkflowoverview-6.checkwalletbalance" id="real-lifescenarios-illustrativeworkflowoverview-6.checkwalletbalance"></a>

Retrieve wallet details and verify the balance associated with the wallet ID. If there are insufficient funds available, ensure you top up your wallet.

{% hint style="info" %}
The wallet ID can be obtained using the Get Wallets List API or the application (under the View Wallet).
{% endhint %}

**Request Example**

<mark style="color:blue;">**`GET`**</mark> /payments/wallets/?id=f6b2776d-53f4-404e-a690-c3766a91d43a

**Response Example**

```json
{
   "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 <a href="#real-lifescenarios-illustrativeworkflowoverview-7.approvepaymentinstruction" id="real-lifescenarios-illustrativeworkflowoverview-7.approvepaymentinstruction"></a>

Review the payment instruction details and approve the transaction by indicating the IDs of the payment.

{% hint style="info" %}
Payment instructions can be obtained using the Get Payment Details API (if the payment ID is known) or by the Get Payments List API.
{% endhint %}

**Request Example**

<mark style="color:yellow;">**`PATCH`**</mark> /payments/payments/approve?id=1573c466-53ba-46e7-a7f2-b6d49c79716b

**Response Examples**

```json
{
  "items": [
    {
      "result": "Approved Successfully",
      "id": "1573c466-53ba-46e7-a7f2-b6d49c79716b",
      "type": "payment"
    }
  ]
}
```

#### &#x20;7. Check Payment Status <a href="#real-lifescenarios-illustrativeworkflowoverview-8.checkpaymentstatus" id="real-lifescenarios-illustrativeworkflowoverview-8.checkpaymentstatus"></a>

Obtain payment information and check the payment status by providing the payment ID.

**Request Example**

<mark style="color:blue;">**`GET`**</mark> /payments/payments/id=1573c466-53ba-46e7-a7f2-b6d49c79716b

**Response Examples**

```json
{
   "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
   }
}
```

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.papayaglobal.com/real-life-scenarios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.