This guide explains how to retrieve charges and payouts, work with payment groups, and confirm outbound wires in the Oyster API.

Note for Reseller partners using the API - you will need to use the X-Oyster-Customer-Id header for relevant calls. For more information, see the Reseller guide to using the Oyster API.

Definitions

Charge: a payment collected from a customer. Every charge is associated with an invoice.

Payout: funds disbursed to a team member (FTE or contractor). Every payout is associated with an invoice.

Charge group: a higher-level bundle of invoices aggregated for payment operations. A group has a unique identifier and it relates to all the invoices underneath it.

For more information about how invoicing at Oyster works and how to use the Invoicing API see the Invoicing at Oyster and Managing Invoices guides.

1. Retrieve individual transactions

The following steps require a chargeId or payoutId. You can retrieve those IDs from the Invoicing API by following the Managing Invoices guide.

1.1 Retrieve a charge

To retrieve information about an individual charge, you can retrieve it with the Retrieve a charge endpoint.

Example request

curl --request GET \
 --url https://api.oysterhr.com/v0.1/charges/chg_111 \
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": {
    "id": "chg_111",
    "status": "PAID",
    "amount": { "decimal": "1000.00", "currencyCode": "USD" },
    "amountDue": { "decimal": "0.00", "currencyCode": "USD" },
    "completedAt": "2022-10-15T12:34:56Z",
    "collectionType": "DIRECT_DEBIT",
    "subject": { "id": "invoice-id-of-chg_111", "type": "INVOICE" }
  }
}

1.2 Retrieve a payout

To get information about an individual payout, you can retrieve it using the Retrieve a payout endpoint.

Example request

curl --request GET \
 --url [https://api.oysterhr.com/v0.1/payouts/](https://api.oysterhr.com/v0.1/payouts/{payoutId})payout123 \
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": {
    "id": "payout123",
    "status": "SENT",
    "amount": {
      "decimal": "1000.00",
      "currencyCode": "USD"
    },
    "statusChanges": [],
    "subject": {
      "id": "payout123",
      "type": "INVOICE"
    }
  }
}

2. Charge groups

Charge groups allow you to group multiple charges into a single payment.

2.1 List charge groups

You can retrieve a list of all charge groups for the company by using the Retrieve all charge groups endpoint.

Example request

curl --request GET \
 --url https://api.oysterhr.com/v0.1/payments/charge-groups \
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": [
    {
      "chargeGroupId": "cg_111222",
      "status": "ready_for_payment",
      "totalAmount": { "value": 225000, "currency": "USD" }
    },
    {
      "chargeGroupId": "cg_333444",
      "status": "paid",
      "totalAmount": { "value": 110000, "currency": "EUR" }
    }
  ]
}

2.2 Retrieve a charge group

To retrieve detailed information about a specific charge group you can use the Retrieve a charge group endpoint.

Example request

curl --request GET \
 --url [https://api.oysterhr.com/v0.1/payments/charge-groups/](https://api.oysterhr.com/v0.1/payments/charge-groups/{chargeGroupId})B67dd74d \
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": {
    "id": "B67dd74d",
    "referenceCode": "OY-COMP-B67dd74d-Gr-0000001",
    "itemsCount": 3,
    "state": "PENDING",
    "amount": {
      "decimal": "726.55",
      "currencyCode": "USD"
    },
    "createdAt": "2022-10-15T12:34:56Z",
    "wireSentAt": null,
    "paidAt": null
  }
}

2.3 Get a detailed list of charges for a charge group

To get a detailed list of charges for a charge group, you can use the Retrieve charge group charges endpoint.

Example request

curl --request GET \
 --url https://api.oysterhr.com/v0.1/payments/charge-groups/B1277a59/charges
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": [
    {
      "id": "B1277a59",
      "status": "WAITING_FOR_WIRE_TRANSFER",
      "amount": { "decimal": "68.30", "currencyCode": "USD" },
      "amountDue": { "decimal": "68.30", "currencyCode": "USD" },
      "completedAt": null,
      "collectionType": "DIRECT_DEBIT",
      "subject": { "id": "Ba234d31", "type": "INVOICE" }
    },
    {
      "id": "F5cbaf60",
      "status": "WAITING_FOR_WIRE_TRANSFER",
      "amount": { "decimal": "83.48", "currencyCode": "USD" },
      "amountDue": { "decimal": "83.48", "currencyCode": "USD" },
      "completedAt": null,
      "collectionType": "DIRECT_DEBIT",
      "subject": { "id": "Dfde14f8", "type": "INVOICE" }
    },
    {
      "id": "J7008331",
      "status": "WAITING_FOR_WIRE_TRANSFER",
      "amount": { "decimal": "90.50", "currencyCode": "USD" },
      "amountDue": { "decimal": "90.50", "currencyCode": "USD" },
      "completedAt": null,
      "collectionType": "DIRECT_DEBIT",
      "subject": { "id": "Face786a", "type": "INVOICE" }
    }
  ],
  "meta": {
    "items": 100,
    "count": 3,
    "page": 1,
    "pages": 1,
    "firstUrl": "/v0.1/payments/charge_groups/B67dd74d/charges?page=1&perPage=100",
    "lastUrl": "/v0.1/payments/charge_groups/B67dd74d/charges?page=1&perPage=100",
    "pageUrl": "/v0.1/payments/charge_groups/B67dd74d/charges?page=1&perPage=100",
    "nextUrl": "/v0.1/payments/charge_groups/B67dd74d/charges?page=&perPage=100",
    "prevUrl": "/v0.1/payments/charge_groups/B67dd74d/charges?page=&perPage=100"
  }
}

3. Manage wire confirmation for a charge group

To confirm that a wire was sent, you can use the Confirm wire sent endpoint.

Example request

curl --request POST \
 --url https://api.oysterhr.com/v0.1/payments/charge-groups/cg_111222/confirm-wire-sent \
 --header 'accept: application/json' \
 --header 'authorization: Bearer BEARER_TOKEN_GOES_HERE'

Response

{
  "data": {
    "id": "cg_111222",
    "referenceCode": "OY-COMP-B67dd74d-Gr-0000001",
    "itemsCount": 0,
    "state": "WIRE_SENT",
    "amount": {
      "decimal": "242.28",
      "currencyCode": "USD"
    },
    "createdAt": "2022-10-15T12:34:56Z",
    "wireSentAt": null,
    "paidAt": null
  }
}

To revoke a wire sent confirmation, use the Revoke wire sent confirmation endpoint.

Example request

curl --request DELETE \
     --url https://api.oysterhr.com/v0.1/payments/charge_groups/cg_111222/wire_sent \
     --header 'accept: application/json'

Response

{
  "data": {
    "id": "cg_111222",
    "referenceCode": "OY-COMP-B67dd74d-Gr-0000001",
    "itemsCount": 0,
    "state": "PENDING",
    "amount": {
      "decimal": "242.28",
      "currencyCode": "USD"
    },
    "createdAt": "2022-10-15T12:34:56Z",
    "wireSentAt": null,
    "paidAt": null
  }
}