Outbound Configuration

Navigate to...
keyboard_arrow_down

.

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 the left navigation within 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 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 198.241.162.104 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 "Credentialssection 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 a reference only. The actual payload you receive will have different values as per your project configuration.

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 from the left navigation within your project depending on which environment the outbound callback 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 acknowledgement 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 on the "Certification" or "Production" page of your project. 
  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.
    1. Download the Visa Development Platform Root Certificate and Visa Development Platform Intermediate Certificate from the "Outbound" section under the "Credentials" section on the "Certification" or "Production" page of your project. 
    2. Add the root CA certificate (and optionally, the intermediate CA certificate) to your trust store (required for Mutual TLS handshake).
      Note: We recommend 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. 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.
  6. Allowlist the Visa Outbound public IP: 198.241.162.104 and IP: 198.241.168.15 at your end so that Visa notification requests are not blocked. For Bangalore allowlist 103.144.116.26. For Mumbai allowlist 198.217.248.24. All VTS clients supporting India cards will need to do the allowlist.
    Note: In an outbound call, Visa acts as a client. You cannot submit a callback configuration for an event that you have already submitted and is in the pending approval state. 
  7. After you are done with your server setup, you can activate the callback using the activation toggle. This will trigger the activation, which will take a few minutes. The callback status in the interim will be "Activation_Pending".
  8. After the activation succeeds, the callback status will change to "Active" and you will be notified (via email) of configuration completion and activation.
  9. You can now proceed for testing configuration via "Ping Test" option available.

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 page for the environment where the outbound callback configuration is to be deactivated from the left navigation within your project. For instance, if the configuration is to be deactivated in the certification environment, click the "Certification" page.
  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".
  7. You may choose to activate the configuration again, as and when required using the toggle.

Note: The outbound callback configuration status remains “Approved” and only state changes to “Active”/”Inactive” via the toggle.

Testing Outbound Callback Configuration


As 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 on the modal will show a sample payload structure as reference. This payload provides information to client on what attributes and values she would receive in the outbound request. 
    Note: The sample payload is non-editable.
  3. Click on "Send Test" and you will receive a payload on your hosted end-point.
  4. The response from your end-point will display on the modal under "Response" section. A 200Ok response means the configuration is successful and the connectivity is established. 
    Note: Make sure you have your end-point setup and server configured correctly. For details, refer to Setup Pre-requisites section.

 

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 page for the environment where the outbound callback configuration is to be deactivated from the left navigation within your project. For instance, if the configuration is to be deactivated in the certification environment, click the "Certification" page.
  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. The configuration domain and path fields will become editable on the modal, which you can modify and submit. A new configuration (endpoint) will be created on the portal and it will be in "Pending" state. Your existing (old) configuration URL will remain “Active” and you will continue to receive outbound calls on it, until the new one is approved.
  7. Visa will acknowledge receipt of your edited configuration and will verify the same.
  8. Post verification, Visa will approve the configuration and old configuration will replace by new (edited) configuration. 
    Note: While the edited configuration is under review and approval, please make sure you have both the old and new URLs hosted.
  9. Once the new configuration is updated it will be updated to “Approved” status and state will be "Active". Your old configuration will cease to exist at this point.

You can now proceed for testing the new configuration via "Ping Test" option.

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.

You can correct the callback URL (domain/path) using the "Edit" option and re-submit the configuration.

The configuration will again undergo verification by Visa.

Outbound Callback Configuration Setup Pre-requisites


For the configuration setup to work:

  1. Your server certificate needs to be issued by one of the Visa trusted CA (Certifying Authority) only. For a detailed list of Visa trusted certifying authorities click here.
  2. 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 for the environment the configuration is to be set up in your project. 
    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. Allowlist the Visa Outbound public IP: 198.241.162.104 and IP: 198.241.168.15 at your end so that Visa notification requests are not blocked. For Bangalore allowlist 103.144.116.26. For Mumbai allowlist 198.217.248.24. All VTS clients supporting India cards will need to do the allowlist.
    Note: In an Outbound call, Visa acts as a client. You cannot submit an outbound callback configuration for an event that you have already submitted and is in the pending approval state.