ON THIS PAGE

Payroll

Ideal for businesses specialising in processing payroll for other businesses.

An offering exclusively from Ebury Mass Payments, it makes instructing mass payouts simple. Paired with our global localised payment network, this will make global payroll simple, efficient and scalable.

API endpoints call sequence

Here is an example of how the APIs can be initiated in a specific sequence to address the use case described above. Feel free to align with our Implementation team if you are looking for additional requirements and optimisations:

Create mass-beneficiaries
Track the status of the mass-beneficiaries creation
Create mass-payment
Track the status of the mass-payment object
Subscribe to our Webhooks to get notified on the status of individual payments

Code snippets

Step 1

Payroll actions are large scale. Use the Create mass-beneficiaries endpoint to create beneficiaries in batches.

curl --location -g '{{APP_URL}}/mass-beneficiaries?client_id={{client_id}}' \
--header 'X-Contact-ID: {{contact_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '[
{
    "name": "New Beneficiary",
    "email_addresses": [
        "new.bene@mail.com"
    ],
    "email_notification": "True",
    "address_line_1": "Address 123",
    "post_code": "1234",
    "country_code": "ES",
    "account_number": "",
    "bank_address_line_1": "",
    "bank_country_code": "ES",
    "bank_currency_code": "EUR",
    "bank_identifier": "",
    "bank_name": "",
    "correspondent_account": "",
    "correspondent_swift_code": "",
    "iban": "ES4401829145013827869416",
    "inn": "",
    "kbk": "",
    "kio": "",
    "kpp": "",
    "reason_for_trade": "",
    "reference_information": "Salary Payment",
    "russian_central_bank_account": "",
    "swift_code": "BBVAESMMXXX",
    "vo": ""
}
]'

Step 2

Track the status of the mass beneficiary creation. Once the individual beneficiaries are ready, you can start with Payroll processing.

curl --location -g '{{APP_URL}}/mass-beneficiaries/{{MASS_BENEFICIARY_ID}}?client_id={{client_id}}' \
--header 'X-Contact-ID: {{contact_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data ''

Step 3

The Create mass-payments endpoints can be used to initiate payments in a large batch. If the currency of the funding account is different than the currency of the beneficiaries, the endpoint can automatically create the necessary trades. No need to create the trade explicitly.

curl --location -g '{{APP_URL}}/mass-payments?client_id={{client_id}}' \
--header 'X-Contact-ID: {{contact_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "auto_commit": "false",
  "sell_currency": "GBP",
  "external_reference_id": "Lorem Ipsum",
  "payment_instructions": [
    {
      "account_number": "208008401",
      "bank_address": "Rue de la Vallee, Brussels",
      "bank_code": "123",
      "bank_country": "BE",
      "bank_name": "",
      "beneficiary_address": "Rue de Coqlicots, Brussels",
      "beneficiary_name": "Tintin",
      "beneficiary_country": "BE",
      "direction": "sell",
      "iban": "BE28123800840120",
      "payment_currency": "CAD",
      "payment_amount": 6.02,
      "purpose_of_payment": "/CCDNDR/",
      "reason_for_trade": "Salary",
      "reference": "BE28123800840120",
      "swift_code": "CTBKBEBX",
      "value_date": "2021-10-28",
      "trade_type": "spot"
    }
  ]
 }'

Step 4

Track the status of the mass payment creation. Once the mass-payment object reaches the state “Created”, the individual payments are created and will be processed.

curl --location -g '{{APP_URL}}/mass-payments?client_id={{client_id}}&mass_payment_id={{MASS_PAYMENT_ID}}' \
--header 'X-Contact-ID: {{contact_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data ''

Step 5

Finally subscribe to Webhooks to get notifications when statuses change on the payment you just initiated.

curl --location -g '{{APP_URL}}/webhooks/graphql?client_id={{client_id}}' \
--header 'X-Contact-ID: {{contact_id}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-api-key: {{api_key}}' \
--header 'Content-Type: application/json' \
--data '{mutation createSubscription {
            createSubscription(
               input: {
                   active: true
                   secret: "secret" 
                   url: "https://httpbin.org/post"
                   types: [PAYMENT_STATUS_CHANGE]
               }
            ) {
              subscription {
                  id
                }
        }
     }
  }'

On This Page

API endpoints call sequence

Code snippets