# 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="https://4141033735-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJKOlaOMAtvjMZO74YRo2%2Fuploads%2FbFRvjzKS4kZPuZLNfpOb%2Fimage.png?alt=media&#x26;token=7604c329-45a3-463a-963f-a9dc6d37f9d6" 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;