Outbound Configuration

Outbound Configuration

Overview

An outbound call is an HTTP callback. A project created with certain APIs on Visa Developer enables you to register the URLs on which you want to listen to the events. The callback triggers an HTTP POST to the configured URL when an event occurs. The client notified on the URL has the flexibility to take appropriate action on the notification.

Note: The outbound configuration is supported only over Two-Way SSL (Mutual Authentication). In order to configure an outbound configuration, you must be a registered user and have either config-only or full access to the product.

Sandbox Setup

Adding Outbound Callback Configuration

To setup an outbound callback:

  1. Login to your Visa Developer account.
  2. Visit the project where the outbound callback configuration is to be set up in.
  3. Click "Sandbox" page from your project.
  4. Visit the "Outbound Callback Configuration" section on the page.
  5. Click "Add Outbound Configuration". This displays a configuration entry dialog box.
  6. Enter details for domain, path (URL), for example, domain: https://testproject.herokuapp.com.

Note: The protocol must be HTTPS. 7. Select the Product and Callback from the dropdown and click "Submit". A new outbound callback configuration will be created in the product section. 8. The outbound callback configuration will be in “Pending” state until it is approved by Visa. 9. Once approved, you will receive an approval mail and the configuration state will be updated to “Approved” on Visa Developer. Your configuration is ready and live at this point. Configuration-related information can be seen via "Details" option. 10. The setup requires configurations, which you need to perform as listed below: 1. Download the Client Outbound Certificate (chain) from the "Outbound" section under the "Credentials" section on the "Sandbox" page of your project. The chain file is a bundled certificate, containing client certificate, intermediate CA, and root CA certificates. 2. Add this certificate chain in the trust store of your application server. Note: Visa recommends clients validate our server certificate by root or intermediate certificate rather than by the leaf certificate itself. This will minimize possible service impacts when we renew our server certificate. 3. Your domain should be publicly available and your server certificate should be issued by a certificate authority included on Visa’s trusted authority list here. 11. Allowlist the Visa Outbound public IP in Sandbox: 198.217.139.45; 198.217.139.47; 198.217.139.42; and 198.217.139.40 at your end so that Visa notification requests are not blocked.

Once your outbound callback configuration is approved for a project, Visa Developer issues an HTTP POST request to the URL specified every time an associated event is triggered. The request's (outbound call) POST parameters will contain XML/JSON data relevant to the event that triggered the request.

Editing Outbound Callback Configuration

You can edit the submitted configuration only after it has been approved by the Visa admin. Select the "Details" option available for your outbound callback configuration and select an "Edit" option (pencil icon), which will allow you to edit the "Domain" and "Path". After you modify the "Domain" parameter, Visa will be notified of it and will review the request for approval. The configuration in the interim will be in “Pending” state. Post Visa approval, the configuration state is updated to “Approved” at which point the configuration is live.

Note: If you only change the "Path" parameter, it will not require a re-approval from Visa.

Rejecting Outbound Callback Configuration

Visa may reject your submitted outbound configuration if there is an issue in verification. If rejected, you will see the configuration in “ Rejected” state on Visa Developer and rejection comments will be available under "Details".

Outbound Callback Configuration Setup Requirements

Two-Way SSL (Mutual Authentication) requires certificate exchange for the client and server to identify themselves and establish a tunnel.

For Sandbox:

  1. Download the Client Outbound Certificate (chain) from the "Outbound" section under the "Credentials" section on the "Sandbox" page of your project. The chain file is a bundled certificate, containing client certificate, intermediate CA and root CA certificates.

  2. You can add this certificate chain in the trust store of your application hosted server or validate our server certificate by root or intermediate certificate. Note: Visa recommends clients validate our server certificate by root or intermediate certificate rather than by the leaf certificate itself. This will minimize possible service impacts when we renew our server certificate.

  3. Your domain should be publicly available and your server certificate should be issued by a certificate authority included on Visa’s trusted authority list here. Self-signed certificates are not accepted.

Note: Clients are responsible for renewing their certificates before they expire. Visa does not store your certificate and thus will not be able to alert you regarding its validity or upcoming expiration.

Testing Outbound Callback Configuration

Visa Developer allows you to test your outbound callback configuration and verify that the URL is reachable by sending a test payload.

  1. Click "Ping Test" which will display the test modal.
  2. Select the Product, Callback and the Callback Event. The request shows a sample payload structure as reference only. The actual payload you receive will have different values as per your project configuration.
  3. Click on "Test Outbound" which will send a payload to your application hosted at the URL specified, and your application response will be displayed on the test modal. Response would be either 200 Ok or 5xx error from your application.

Certification and Production Setup

Adding Outbound Callback Configuration

Note: For the certification and production environment, the outbound callback configuration can only be added after your project is promoted to the environment.

  1. Login to your Visa Developer account.
  2. Visit the project where the outbound callback configuration is to be set up in.
  3. Click "Certification" or "Production" page depending on which environment the configuration needs to be set up in.
  4. Visit the "Outbound Callback Configuration" section on the page.
  5. Click "Add Outbound Configuration". This displays a configuration entry dialog box.
  6. Select the outbound API, enter configuration details: domain, path and click "Submit". For example, domain: https://testproject.herokuapp.com.

Note: The protocol must be HTTPS. 7. A new outbound configuration will be added for the API and you will get an acknowledgment mail. 8. The configuration will be in “Pending” state and Visa will verify the configuration details before approving.

Verifying and Activating Outbound Callback Configuration

To verify and activate an outbound callback configuration, consider the following:

  1. Visa will review your submitted configuration, and once reviewed the configuration may be approved.
  2. An approval will trigger provisioning of your outbound certificate.
  3. Once the outbound certificate is provisioned, the configuration status will change to "Approved" and the configuration state will be “Inactive.”
  4. The certificate provisioning will provide the outbound certificate, intermediate CA and root CA certificates for you to download from the "Outbound" section under the "Credentials" section.
  5. Visa will notify you (via email) of the outbound certificate provisioning and as a next step, you will be required to configure your server. Refer to steps below or read Outbound Configuration Setup Pre-requisites for more details.

De-activating Outbound Callback Configuration

You can de-activate an active outbound callback configuration anytime from Visa Developer.

  1. Login to your Visa Developer account.
  2. Visit the project where the outbound callback configuration is to be deactivated.
  3. Click the page for the environment where the outbound callback configuration is to be deactivated.
  4. Visit the "Outbound Callback Configuration" section on the page.
  5. Disable the callback using the toggle, which when exercised will change the state of callback to "De-activation_Pending".
  6. Post de-activation is successful, the configuration state will change to "Inactive.".

Testing Outbound Callback Configuration

Once your outbound callback configuration is activated and the state reflects as "Active", you can proceed to test the same using "Ping Test".

  1. Click on "Ping Test" option for the callback and a modal will be displayed listing the Product, Outbound API, and API end-point.
  2. The "Request" section will show a sample payload structure as reference.
  3. Click on "Send Test" and you will receive a payload on your hosted end-point.

Note: Make sure you have your end-point setup and server configured correctly.

Editing Outbound Callback Configuration

To edit an outbound callback configuration:

  1. Login to your Visa Developer account.
  2. Visit the project where the outbound callback configuration is to be deactivated.
  3. Click the page for the environment where the outbound callback configuration is to be deactivated.
  4. Visit the "Outbound Callback Configuration" section on the page.
  5. Click on "Details" option for the configuration you want to edit.
  6. Select the "Edit" option (pencil icon) from the top of the Edit modal.

Note: You cannot edit a configuration that is in "Pending" state.

  1. Visa will acknowledge receipt of your edited configuration and will verify the same.
  2. Post verification, Visa will approve the configuration and the old configuration will be replaced by the new (edited) configuration.

Deleting Outbound Callback Configuration

To delete an outbound callback configuration, contact your Visa representative.

Visa Admin will need to initiate the configuration deletion on your behalf. The SLA to complete a deletion is 3-4 days. You will not be able to submit a new outbound callback configuration until your delete request has entered the "Pending" state.

Re-submitting Rejected Outbound Callback Configuration

Visa has the right to reject an outbound callback configuration submitted by you if it finds that domain is not valid or it is not owned by you. Visa will provide rejection comments which will be visible to you on the Developer portal in “Comments” field under “Details” modal.

The configuration status will be "Rejected" on Visa Developer dashboard.

Outbound Callback Configuration Setup Pre-requisites

  1. For the configuration setup to work:
  2. Your server certificate needs to be issued by one of the Visa trusted CA only. For a detailed list of Visa trusted certifying authorities click here.
  3. You need to add Visa's root CA certificate (and optionally, Visa's intermediate CA certificate) to your server's trust store. Download the Visa Development Platform Root Certificate and Visa Development Platform Intermediate Certificate from the "Credentials" section on the page.