Notification callback

​ Notifications callback allows you to specify the URL to where OFX Payments API will push events by adding the new header called “callback-url” to Deal Creation API request.

We currently started with the “DealCreated” event, which contains the Process Id and Deal Id or Error. Event will be pushed to your listener URL service via POST command.

We also support the nonce value if you would like to add extra tracking, correlation or security to your service by adding another new header called “callback-nonce” to Deal Creation API request. The nonce value will be returned back to your callback url together with event. ​

Notifications structure

​ To receive the Deal Creation Notification you should specify 2 extra headers during the Deal Creation process:

Extra headers:

callback-location: <<your callback url>>
callback-nonce: <<your callback nonce value>>
  • callback-location - Could be any URL to where OFX will send the the notification event.
  • callback-nonce - Will be returned back to your callback url for tracking reasons

Deal Creation Notification

Create a deal

Below is the example of Deal Creation Notification:

curl -X POST \
  https://sandbox.api.ofx.com/v1/payments/deals/spot \
  -H 'authorization: Bearer your_access_token' \
  -H 'content-type: application/json' \
  -H 'callback-location: https://mysite.com/callback' \
  -H 'callback-nonce: My nonce value' \
  -d {
    "quoteId": "2e2aadc8-d69b-45d5-9f14-8b08a2365d90",
    "fundingSource": "Direct Debit",
    "channel": "OFXSecure",
    "beneficiaries" : [{
          "beneficiaryId": "2f1901fa-17e0-486f-87fe-42371f97c957",
          "amount": 13304,
          "payReason": "PayReason",
          "payReference": "PayReference"
    }]
}

Response:

{
  "processId": "833771b4-b7db-4770-83ba-6e69d88e1631"
}

See Create a Spot Deal section for details.

Receive a notification

You will receive the POST request with the below event body to specified callback-location URL once deal is created.

The even can be successfull with deal Id or failed with error.

Deal Creation successful event

POST https://mysite.com/callback
Headers: callback-nonce: My nonce value
{
  "status": "success",
  "eventType": "DealCreated",
  "eventBody": {
    "processId": "833771b4-b7db-4770-83ba-6e69d88e1631",
    "dealId": "d7e59678-8608-498e-a8bc-7ab44017dd90"
  }
}

Deal Creation failed event

POST https://mysite.com/callback
Headers: callback-nonce: My nonce value
{
  "status": "fail",
  "eventType": "DealCreated",
  "eventBody": {
    "processId": "833771b4-b7db-4770-83ba-6e69d88e1631",
    "errors": [
      {
        "errorCode": "BE:BeneficiaryValidator:0003",
        "fieldName": "PaymentReason",
        "message": "'Payment Reason' should not be empty."
      }
    ]
  }
}