1. Oracle Global Human Resources Cloud REST APIREST API for Oracle Fusion Cloud HCM
  2. Use Cases
  3. Global Payroll
  4. Manage Personal Payment Methods

Manage Personal Payment Methods

A personal payment method associates a person to a payment method, currency, and payment source. You can use the payment method REST services to create, update, and retrieve payment methods.

The personalPaymentMethods resource includes a list of all personal payment methods for a given payroll relationship.

In this use case, we discuss these scenarios:

  • Create a Personal Payment Method

  • Update the Payment Amount Type

  • Retrieve Multiple Personal Payment Methods

Create a Personal Payment Method

Let's say that Robin wants to sign up for Direct Deposit of his pay checks. For his personal payment method, you specify the Organization Payment Method and the payment amount type in the Oracle HCM Cloud. 

Also, you create these bank account details for his Checking account in the Oracle Financials Cloud.

Here's a graphic to help you understand this scenario.

Create Personal Payment Method

To create a personal payment method:

  1. Perform a POST operation on the personalPaymentMethods resource by providing the worker details in the request body.
  2. Verify the details returned in the response.

Example URL

Use this resource URL format.

POST

https://<host>:<port>/hcmRestApi/resources/11.13.18.05/personalPaymentMethods

Example Request

Here's an example of the request body in JSON format.

{
  "Name": "EFT Payment Method",
  "EffectiveStartDate": "2010-02-01",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100014505486,
  "BankAccountId": 1212101011,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 100,
  "Priority": 10,
  "PayrollRelationshipId": 300100006014818
}

You can retrieve PayrollRelationshipId from the payrollRelationships and BankAccountId from the /externalBankAccounts REST resources. For more information on External Bank Accounts, refer to the REST API for Oracle Financials Cloud guide.

Example Response

Here's an example of the response body in JSON format.

{
  "PersonalPaymentMethodId": 300100181650103,
  "Name": "EFT Payment Method",
  "EffectiveStartDate": "2010-10-12",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100005800591,
  "BankAccountId": 1212101011,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 100,
  "Priority": 10,
  "PayrollRelationshipId": 300100006014818,
  "PartyId": 300100006001613,
  "PersonNumber": "300100006014805",
  "links": []
}

Update the Payment Amount Type

For each pay period, Julie had opted for a fixed payment amount to be transferred to her husband???s account. After her recent promotion as the Sales Manager, she expects to receive frequent bonuses and sales commissions. Because Julie???s net payment amount always changes, she decides to allocate four percent of her pay to the fund. She updates her personal payment method to use Percentage as the payment amount type.

By using a percentage rather than a fixed amount, she can now contribute to the fund at the same rate that she earns.

To update the payment amount type:

  1. Perform a PATCH operation on this URL to update the payment amount type as Percentage.
  2. Verify the details returned in the response.

Example URL

Use this resource URL format.

PATCH

https://<host>:<port>/hcmRestApi/resources/11.13.18.05/personalPaymentMethods/<<Generated Personal Payment Method Id>>

Example Request

Here's an example of the request body in JSON format.

{
  "PersonalPaymentMethodId": 300100181650365,
  "Name": "Cheque Payment Method",
  "EffectiveStartDate": "2010-10-12",
  "EffectiveEndDate": "4712-12-31",
  "Percentage": 4,
  "PayrollRelationshipId": 300100006014818
}

Example Response

Here's an example of the response body in JSON format.

{
  "PersonalPaymentMethodId": 300100181650365,
  "Name": "Cheque Payment Method",
  "EffectiveStartDate": "2016-01-01",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100005800591,
  "BankAccountId": null,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 4,
  "Priority": 20,
  "PayrollRelationshipId": 300100006014818,
  "PartyId": 300100006001613,
  "PersonNumber": "300100006014805",
  "links": []
}

Retrieve Multiple Personal Payment Methods

Jim works in Arizona, but his wife and children live in Texas. For each payroll period, Jim wants these disbursements:

  • 900 USD transferred to his checking account for his wife's household expenses in Texas.

  • A percentage transferred to his children's college fund.

  • The remainder paid to him by check for his expenses in Arizona.

Jim creates three payment methods by submitting a POST request on the payrollRelationships resource:

  1. A check payment method for remaining pay.

  2. An EFT payment method with the college fund bank account details.

  3. An EFT payment method with his checking account bank details.

Now, he wants to view all his payment methods. To view the details, he submits the GET request on the payrollRelationships resource.

Here's a graphic to help you understand this scenario.

Retrieve Payment Method

To retrieve all the personal payment methods:

  1. Submit a GET request on the payrollRelationships resource.

  2. Verify the details returned in the response.

Example URL

Use this resource URL format.

PATCH

https://<host>:<port>/hcmRestApi/resources/11.13.18.05/personalPaymentMethods

GET

https://<host>:<port>/hcmRestApi/resources/11.13.18.05/personalPaymentMethods

Example Request

Here's an example of request body in JSON format to create a check payment method:

{
  "Name": "Check Payment Method",
  "EffectiveEndDate": "4712-12-31",
  "EffectiveStartDate": "2020-03-03",
  "BankAccountId": null,
  "OrgPaymentMethodId": 300100003245042,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 100,
  "Priority": 30,
  "PayrollRelationshipId": 300100006342199
}

Here's an example of request body in JSON format to create an EFT payment method with the college fund bank account details:

{
  "Name": "EFT with college account",
  "EffectiveStartDate": "2020-03-03",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100003245046,
  "BankAccountId": 143814,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 10,
  "Priority": 20,
  "PayrollRelationshipId": 300100006342199
}

Here's an example of request body in JSON format to create an EFT payment method with checking account bank details.

{   
"Name": "EFT with Checking account",  
"EffectiveStartDate": "2020-03-03",    
"EffectiveEndDate": "4712-12-31",
"OrgPaymentMethodId": 300100003245046,
"BankAccountId": 143813,
"PaymentAmountType": "M", 
"Amount": 900,
"Percentage": null,
"Priority": 10,
"PayrollRelationshipId": 300100006342199
}

Example Response

Here are examples of response body in JSON format.

PATCH

Create a check payment method

{
  "PersonalPaymentMethodId": 300100210071144,
  "Name": "Check Payment Method",
  "EffectiveStartDate": "2020-03-03",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100003245042,
  "BankAccountId": null,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 100,
  "Priority": 30,
  "PayrollRelationshipId": 300100006342199,
  "PartyId": 300100006257275,
  "PersonNumber": "300100006342154",
  "links": []
}
Create an EFT payment method 
{
  "PersonalPaymentMethodId": 300100210089777,
  "Name": "EFT with college account",
  "EffectiveStartDate": "2020-03-03",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100003245046,
  "BankAccountId": 143814,
  "PaymentAmountType": "P",
  "Amount": null,
  "Percentage": 10,
  "Priority": 20,
  "PayrollRelationshipId": 300100006342199,
  "PartyId": 300100006257275,
  "PersonNumber": "300100006342154",
  "links": []
}

EFT payment method with checking account bank details. 

{
  "PersonalPaymentMethodId": 300100210095298,
  "Name": "EFT with Checking account",
  "EffectiveStartDate": "2020-03-03",
  "EffectiveEndDate": "4712-12-31",
  "OrgPaymentMethodId": 300100003245046,
  "BankAccountId": 143813,
  "PaymentAmountType": "M",
  "Amount": 900,
  "Percentage": null,
  "Priority": 10,
  "PayrollRelationshipId": 300100006342199,
  "PartyId": 300100006257275,
  "PersonNumber": "300100006342154",
  "links": []
}

GET 

{
  "items": [
    {
      "PersonalPaymentMethodId": 300100209940943,
      "Name": "EFT with Checking account",
      "EffectiveStartDate": "2020-03-03",
      "EffectiveEndDate": "4712-12-31",
      "OrgPaymentMethodId": 300100003245046,
      "BankAccountId": 143813,
      "PaymentAmountType": "M",
      "Amount": 900,
      "Percentage": null,
      "Priority": 10,
      "PayrollRelationshipId": 300100006342199,
      "PartyId": 300100006257275,
      "PersonNumber": "300100006342154",
      "links": []
    },
    {
      "PersonalPaymentMethodId": 300100209940940,
      "Name": "EFT with college account",
      "EffectiveStartDate": "2020-03-03",
      "EffectiveEndDate": "4712-12-31",
      "OrgPaymentMethodId": 300100003245046,
      "BankAccountId": 143814,
      "PaymentAmountType": "P",
      "Amount": null,
      "Percentage": 10,
      "Priority": 20,
      "PayrollRelationshipId": 300100006342199,
      "PartyId": 300100006257275,
      "PersonNumber": "300100006342154",
      "links": []
    },
    {
      "PersonalPaymentMethodId": 300100209940792,
      "Name": "Check Payment Method",
      "EffectiveStartDate": "2020-03-03",
      "EffectiveEndDate": "4712-12-31",
      "OrgPaymentMethodId": 300100003245042,
      "BankAccountId": null,
      "PaymentAmountType": "P",
      "Amount": null,
      "Percentage": 100,
      "Priority": 30,
      "PayrollRelationshipId": 300100006342199,
      "PartyId": 300100006257275,
      "PersonNumber": "300100006342154",
      "links": []
    }
  ],
  "count": 3,
  "hasMore": false,
  "limit": 25,
  "offset": 0,
  "links": []
}