Push Notifications
Summary
Push Notifications, a.k.a. webhooks, allow you to set up integrations that correspond with ‘notifications’ from Currencycloud.
There is a set of events described below that can trigger push notifications on the Currencycloud Platform. When one of these events is triggered, we send an HTTP POST command to the webhook’s URL. This allows you to track transactions and state changes in a more efficient manner and automate communications internally or with your customers.
When you are ready to get set up with push notifications, please contact your Solutions Manager.
Notifications
The following entities and events generate push notifications on the Currencycloud platform. These events can be configured individually to generate a push notification.
Payments
The following diagram presents the different status payments go through during their lifecycle on the platform. This also highlights which statuses trigger push notifications.
Below are some examples of the push notifications described in the diagram above.
| Message Header |
Content-Length: 681
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Ready To Send Notification |
| Push Notification |
{
"header": {
"message_type": "payment",
"notification_type": "payment_ready_to_send_notification"
},
"body": {
"id": "a634d8c2-f520-4cba-985c-77dc1e0cc9af",
"amount": "2000.00",
"failure_returned_amount": "2000.00",
"beneficiary_id": "509c6dd0-6b26-4fec-930f-937ddc428bba",
"conversion_id": "e5e8c287-73c3-4998-a368-47937301e471",
"currency": "GBP",
"reference": "cc",
"reason": "test",
"status": "ready_to_send",
"payment_type": "priority",
"payment_date": "2018-04-30 00:00:00 +0000",
"transferred_at": "2018-04-30 08:39:25 +0000",
"authorisation_steps_required": "0",
"creator_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"last_updater_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"short_reference": "180430-TSLCQJ001",
"failure_reason": "",
"payment_group_id":null,
"unique_request_id":"Ciu4eNcYnq582hwK_8Cu47sk"
}
|
| Message Header |
Content-Length: 734
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Payment Released Notification |
| Push Notification |
{
"header": {
"message_type": "payment",
"notification_type": "payment_released_notification"
},
"body": {
"id": "a634d8c2-f520-4cba-985c-77dc1e0cc9af",
"amount": "2000.00",
"failure_returned_amount": "2000.00",
"beneficiary_id": "509c6dd0-6b26-4fec-930f-937ddc428bba",
"conversion_id": "e5e8c287-73c3-4998-a368-47937301e471",
"currency": "GBP",
"reference": "cc",
"reason": "test",
"status": "completed",
"payment_type": "priority",
"payment_date": "2018-04-30 00:00:00 +0000",
"transferred_at": "2018-04-30 08:39:25 +0000",
"authorisation_steps_required": "0",
"creator_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"last_updater_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"short_reference": "180430-TSLCQJ001",
"failure_reason": "",
"payment_group_id":null,
"unique_request_id":"Ciu4eNcYnq582hwK_8Cu47sk"
}
}
|
| Message Header |
Content-Length: 757
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Payment Failed Notification |
| Push Notification |
{
"header": {
"message_type": "payment",
"notification_type": "payment_failed_notification"
},
"body": {
"id": "a634d8c2-f520-4cba-985c-77dc1e0cc9af",
"amount": "2000.00",
"failure_returned_amount": "2000.00",
"beneficiary_id": "509c6dd0-6b26-4fec-930f-937ddc428bba",
"conversion_id": "e5e8c287-73c3-4998-a368-47937301e471",
"currency": "GBP",
"reference": "cc",
"reason": "test",
"status": "failed",
"payment_type": "priority",
"payment_date": "2018-04-30 00:00:00 +0000",
"transferred_at": "2018-04-30 08:39:25 +0000",
"authorisation_steps_required": "0",
"creator_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"last_updater_contact_id": "202b6291-99b4-0132-60c0-10b11cb33cfb",
"short_reference": "180430-TSLCQJ001",
"failure_reason": "Test Fail",
"payment_group_id":null,
"unique_request_id":"Ciu4eNcYnq582hwK_8Cu47sk"
}
}
|
| Message Header |
Content-Length: 743
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Payment Compliance Failed |
| Push Notification |
{
"header":{
"message_type":"payment",
"notification_type":"payment_compliance_failed_notification"
},
"body":{
"id":"ff13cd8a-d0b3-473c-a6e8-f68bc079aff8",
"amount":"2000.00",
"failure_returned_amount":"2000.00",
"beneficiary_id":"509c6dd0-6b26-4fec-930f-937ddc428bba",
"conversion_id":null,
"currency":"GBP",
"reference":"rrr",
"reason":"test",
"status":"failed",
"payment_type":"priority",
"payment_date":"2018-07-27T00:00:00+00:00",
"transferred_at":null,
"authorisation_steps_required":0,
"creator_contact_id":"eb5ecd81-f800-0132-a9c5-10b11cb33cfb",
"last_updater_contact_id":"eb5ecd81-f800-0132-a9c5-10b11cb33cfb",
"short_reference":"180727-GYJLVG001",
"failure_reason":"Compliance failed 1",
"payment_group_id":null,
"unique_request_id":"Ciu4eNcYnq582hwK_8Cu47sk"
}
}
|
Conversion
The following diagram presents the different statuses that a conversion goes through during its lifecycle on the platform. The diagram describes also which statuses trigger events that are covered by push notifications.
Below are some examples of the push notifications described in the diagram above.
| Message Header |
Content-Length: 932
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Cash Manager Trade Notification |
| Push Notification |
{
"header":{
"message_type":"conversion",
"notification_type":"cash_manager_trade_notification"
},
"body":{
"id":"a0d9034e-bc9f-45e7-a1e4-6485735794c0",
"account_id":"d2b04c30-9585-4ba6-acea-bf9add10444d",
"creator_contact_id":"669b4860-4bb3-4636-8ee4-9e672810d350",
"short_reference":"20180430-GBMHXC",
"created_at":"2018-04-30T12:49:06+00:00",
"settlement_date":"2018-04-30T15:30:00+00:00",
"conversion_date":"2018-04-30T00:00:00+00:00",
"status":"awaiting_funds",
"partner_status":"awaiting_funds",
"currency_pair":"GBPUSD",
"buy_currency":"USD",
"sell_currency":"GBP",
"fixed_side":"sell",
"partner_buy_amount":"0.00",
"partner_sell_amount":"0.00",
"client_buy_amount":"96565.00",
"client_sell_amount":"70000.00",
"mid_market_rate":"1.4078",
"core_rate":"1.4077",
"partner_rate":"",
"client_rate":"1.3795",
"deposit_required":false,
"deposit_amount":"0.00",
"deposit_currency":"",
"deposit_status":"not_required",
"deposit_required_at":"",
"payment_ids":[]
}
}
|
| Message Header |
Content-Length: 927
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Funds Arrived Notification |
| Push Notification |
{
"header":{
"message_type":"conversion",
"notification_type":"funds_arrived_notification"
},
"body":{
"id":"a0d9034e-bc9f-45e7-a1e4-6485735794c0",
"account_id":"d2b04c30-9585-4ba6-acea-bf9add10444d",
"creator_contact_id":"669b4860-4bb3-4636-8ee4-9e672810d350",
"short_reference":"20180430-GBMHXC",
"created_at":"2018-04-30T12:49:06+00:00",
"settlement_date":"2018-04-30T15:30:00+00:00",
"conversion_date":"2018-04-30T00:00:00+00:00",
"status":"funds_arrived",
"partner_status":"funds_arrived",
"currency_pair":"GBPUSD",
"buy_currency":"USD",
"sell_currency":"GBP",
"fixed_side":"sell",
"partner_buy_amount":"0.00",
"partner_sell_amount":"0.00",
"client_buy_amount":"96565.00",
"client_sell_amount":"70000.00",
"mid_market_rate":"0.7103",
"core_rate":"0.7104",
"partner_rate":"",
"client_rate":"0.7249",
"deposit_required":null,
"deposit_amount":"0.00",
"deposit_currency":"",
"deposit_status":"not_required",
"deposit_required_at":"",
"payment_ids":[]
}
}
|
| Message Header |
Content-Length: 922
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Trade Settled Notification |
| Push Notification |
{
"header":{
"message_type":"conversion",
"notification_type":"trade_settled_notification"
},
"body":{
"id":"a0d9034e-bc9f-45e7-a1e4-6485735794c0",
"account_id":"d2b04c30-9585-4ba6-acea-bf9add10444d",
"creator_contact_id":"669b4860-4bb3-4636-8ee4-9e672810d350",
"short_reference":"20180430-GBMHXC",
"created_at":"2018-04-30T12:49:06+00:00",
"settlement_date":"2018-04-30T15:30:00+00:00",
"conversion_date":"2018-04-30T00:00:00+00:00",
"status":"trade_settled",
"partner_status":"trade_settled",
"currency_pair":"GBPUSD",
"buy_currency":"USD",
"sell_currency":"GBP",
"fixed_side":"sell",
"partner_buy_amount":"0.00",
"partner_sell_amount":"0.00",
"client_buy_amount":"96565.00",
"client_sell_amount":"70000.00",
"mid_market_rate":"0.7103",
"core_rate":"0.7104",
"partner_rate":"",
"client_rate":"0.7249",
"deposit_required":false,
"deposit_amount":"0.00",
"deposit_currency":"",
"deposit_status":"not_required",
"deposit_required_at":"",
"payment_ids":[]
}
}
|
| Message Header |
Content-Length: 924
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Trade Closed Notification |
| Push Notification |
{
"header":{
"message_type":"conversion",
"notification_type":"trade_closed_notification"
},
"body":{
"id":"a0d9034e-bc9f-45e7-a1e4-6485735794c0",
"account_id":"d2b04c30-9585-4ba6-acea-bf9add10444d",
"creator_contact_id":"669b4860-4bb3-4636-8ee4-9e672810d350",
"short_reference":"20180430-GBMHXC",
"created_at":"2018-04-30T12:49:06+00:00",
"settlement_date":"2018-04-30T15:30:00+00:00",
"conversion_date":"2018-04-30T00:00:00+00:00",
"status":"closed",
"partner_status":"closed_other",
"currency_pair":"GBPUSD",
"buy_currency":"USD",
"sell_currency":"GBP",
"fixed_side":"sell",
"partner_buy_amount":"0.00",
"partner_sell_amount":"0.00",
"client_buy_amount":"96565.00",
"client_sell_amount":"70000.00",
"mid_market_rate":"0.7103",
"core_rate":"0.7104",
"partner_rate":"",
"client_rate":"0.7249",
"deposit_required":false,
"deposit_amount":"0.00",
"deposit_currency":"",
"deposit_status":"not_required",
"deposit_required_at":"",
"payment_ids":[]
}
}
|
| Message Header |
Content-Length: 955
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Deposit Arrived Notification |
| Push Notification |
{
"header":
{
"message_type":"conversion",
"notification_type":"deposit_arrived_notification"
},
"body":
{
"id":"991e203b-5001-4cca-83f4-606e6543f6cd",
"account_id":"9658df0c-a7cd-d9c9-274a-4e81bdf5f64a",
"creator_contact_id":"a3180fae-4c77-6dfb-74b3-4f16d55d6d1d",
"short_reference":"20180514-TCNZVW",
"created_at":"2018-05-14T07:24:06+00:00",
"settlement_date":"2018-05-17T13:00:00+00:00",
"conversion_date":"2018-05-17T00:00:00+00:00",
"status":"awaiting_funds",
"partner_status":"funds_arrived",
"currency_pair":"GBPUSD",
"buy_currency":"GBP",
"sell_currency":"USD",
"fixed_side":"buy",
"partner_buy_amount":"0.00",
"partner_sell_amount":"0.00",
"client_buy_amount":"1500.00",
"client_sell_amount":"2115.90",
"mid_market_rate":"0.7092",
"core_rate":"0.7092",
"partner_rate":"",
"client_rate":"0.7089",
"deposit_required":true,
"deposit_amount":"63.48",
"deposit_currency":"USD",
"deposit_status":"deposit_received",
"deposit_required_at":"2018-05-16T13:00:00+00:00",
"payment_ids":[]
}
}
|
Transfer
The following diagram presents the different statuses that a transfer goes through during its lifecycle on the platform. The diagram describes also which statuses trigger events that are covered by push notifications.
Below are some examples of the push notifications described in the diagram above.
| Message Header |
Content-Length: 612
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Transfer Created Notification |
| Push Notification |
{
"header":{
"message_type":"transfer",
"notification_type":"transfer_created_notification"
},
"body":{
"id":"c30f5835-2544-41d8-bf0c-4868669b637d",
"short_reference":"BT-20180511-KZTTYX",
"source_account_id":"e0bf0629-56e7-42f2-84a4-3528168ee21c",
"destination_account_id":"10a1ba3d-10f8-400e-89fa-8fafa323cc96",
"currency":"USD",
"amount":"300.00",
"status":"pending",
"created_at":"2018-05-11T13:21:43+00:00",
"updated_at":"2018-05-11T13:21:43+00:00",
"completed_at":null,
"creator_account_id":"2090939e-b2f7-3f2b-1363-4d235b3f58af",
"creator_contact_id":"8a98ebac-6f88-e205-a685-4d235b1b088b",
"reason":"moving funds 2 -> 3"
}
}
|
| Message Header |
Content-Length: 639
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Transfer Completed Notification |
| Push Notification |
{
"header":{
"message_type":"transfer",
"notification_type":"transfer_completed_notification"
},
"body":{
"id":"c30f5835-2544-41d8-bf0c-4868669b637d",
"short_reference":"BT-20180511-KZTTYX",
"source_account_id":"e0bf0629-56e7-42f2-84a4-3528168ee21c",
"destination_account_id":"10a1ba3d-10f8-400e-89fa-8fafa323cc96",
"currency":"USD",
"amount":"300.00",
"status":"completed",
"created_at":"2018-05-11T13:21:43+00:00",
"updated_at":"2018-05-11T13:21:44+00:00",
"completed_at":"2018-05-11T13:21:44+00:00",
"creator_account_id":"2090939e-b2f7-3f2b-1363-4d235b3f58af",
"creator_contact_id":"8a98ebac-6f88-e205-a685-4d235b1b088b",
"reason":"moving funds 2 -> 3"
}
}
|
Funding Transaction
The following diagram presents the details of a funding transaction.
Below are some examples of the push notifications described in the diagram above.
| Message Header |
Content-Length: 723
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Pending Cash Manager Transaction Notification |
| Push Notification |
{
"header": {
"message_type": "cash_manager_transaction",
"notification_type": "pending_cash_manager_transaction_notification"
},
"body": {
"id": "0c54e5d6-afd8-4eab-b82f-f2371467d79f",
"balance_id": "b7a0b206-4dfd-48e6-aa7b-1b6514b76148",
"account_id": "8427390b-21cc-41f5-b3b4-8ce20d770053",
"currency": "EUR",
"amount": "1000.00",
"balance_amount": "1000.00",
"type": "credit",
"related_entity_type": "inbound_funds",
"related_entity_id": "46d8d68f-9fb1-41ba-9d67-708dc36d0cf1",
"related_entity_short_reference": "IF-20200616-MMZ57O",
"status": "pending",
"reason": "",
"settles_at": null,
"created_at": "2020-06-16T12:13:47+00:00",
"updated_at": "2020-06-16T12:13:47+00:00",
"completed_at": null,
"action": "funding"
}
}
|
| Message Header |
Content-Length: 742
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Rejected Cash Manager Transaction Notification |
| Push Notification |
{
"header": {
"message_type": "cash_manager_transaction",
"notification_type": "rejected_cash_manager_transaction_notification"
},
"body": {
"id": "0c54e5d6-afd8-4eab-b82f-f2371467d79f",
"balance_id": "b7a0b206-4dfd-48e6-aa7b-1b6514b76148",
"account_id": "8427390b-21cc-41f5-b3b4-8ce20d770053",
"currency": "EUR",
"amount": "1000.00",
"balance_amount": "1000.00",
"type": "credit",
"related_entity_type": "inbound_funds",
"related_entity_id": "46d8d68f-9fb1-41ba-9d67-708dc36d0cf1",
"related_entity_short_reference": "IF-20200616-MMZ57O",
"status": "deleted",
"reason": "",
"settles_at": null,
"created_at": "2020-06-16T12:13:47+00:00",
"updated_at": "2020-06-16T12:13:47+00:00",
"completed_at": null,
"action": "funding"
}
}
|
| Message Header |
Content-Length: 711
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Ruby
Host: WS00CC014:8000
Content-Type: text/plain
|
| Notification Type |
Cash Manager Transaction Notification |
| Push Notification |
{
"header":{
"message_type":"cash_manager_transaction",
"notification_type":"cash_manager_transaction_notification"
},
"body":{
"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"balance_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"account_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currency":"EUR",
"amount":"100000.00",
"balance_amount":"100000.00",
"type":"credit",
"related_entity_type":"inbound_funds",
"related_entity_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"related_entity_short_reference":"",
"status":"completed",
"reason":"",
"settles_at":"2018-01-05T14:39:41+00:00",
"created_at":"2018-01-05T14:39:41+00:00",
"updated_at":"2018-01-05T14:39:41+00:00",
"completed_at":"2018-01-05T14:39:41+00:00",
"action":"funding"
}
}
|