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 full access to the product.

Sandbox Setup

Adding Outbound Configuration

To setup an outbound callback:

  1. Login to your Visa Developer account.
  2. Click on Project and go to Configuration section on your dashboard.
  3. Click on Add Outbound Configuration. This displays a configuration entry dialog box.
  4. Enter details for domain, path (URL), for example, domain: https://testproject.herokuapp.com.
    Note: The protocol must be HTTPS.
  5. Select the Product and Callback from the dropdown and click Submit.  A new callback configuration will be created in the product section.
  6. The callback configuration will be in “Pending” state until it is approved by Visa.
  7. 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.
  8. The setup requires configurations, which you need to perform as listed below:
    1. Download the Client Outbound Certificate (chain) from the Outbound Certificates section under Credentials tab of your Project on Visa Developer. The chain file is a bundled certificate, containing client certificate, VICA intermediate and VICA root 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. 
      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.
  9. Whitelist the Visa Outbound public IP 198.241.162.104 at your end so that Visa notification requests are not blocked.

Once your outbound 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 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 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 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 Configuration Setup Requirements

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

For Sandbox:

  1. Download the Client Outbound Certificate (chain) from the Outbound Certificates section under Credentials tab of your Project on Visa Developer.  The chain file is a bundled certificate, containing client certificate, VICA intermediate and VICA root certificates.  
  2. Add this certificate chain in the trust store of your application hosted 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. 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 Configuration

Visa Developer allows you to test your outbound 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 Configuration

You can submit outbound API configurations in certification and production from Visa Developer via project promotion request or from Configuration section of the project once it is promoted to certification or production environment.

Via Project Promotion
  1. Your project promotion request form (for certification or production) will have your outbound APIs also promoted to higher environment.
  2. You can enter the configuration details (domain and path) in the promotion form for each of the outbound APIs and submit the form. 
    Note: The outbound configuration submission from promotion request will be optional.
  3. Post submission Visa will review your promotion request.
  4. If the request is reviewed and approved by Visa and an applicable VDP API Agreement is in place, your project will be promoted to certification or production (as requested) and you will be notified of the same by mail.
  5. You will receive acknowledgement mail for your submitted outbound configurations and Visa will verify those for approval.
  6. You can login to your Visa Developer account and go to your project Configuration section, where you will notice the outbound configuration(s) in "Pending" state.
Via Project Configuration Section

You can also submit outbound API configurations for your project from Configuration section.

Note: For certification and production environment, your project promotion request should be Visa approved before you can access Configuration section.

  1. Login to your Visa Developer account.
  2. Click on the Project and go to Configuration section on your project (certification or production to which your project is promoted).
  3. Click on Add Outbound Configuration. This displays a configuration submission modal.
  4. 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.
  5. A new outbound configuration will be added for the API and you will get an acknowledgement mail.
  6. The configuration will be in “Pending” state and Visa will verify the configuration details before approving.

Verifying and Activating Outbound Configuration

To verify and activate Outbound 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 public client certificate (Visa Information Delivery Certifying Authority signed). 
    Note: The SLA for provisioning the client certificate is 3 to 4 days.
  3. Once the client certificate is provisioned, the configuration status will change to "Approved" and the configuration state will be “Inactive”.
  4. The certificate provisioning will provide the public certificate, VICA intermediate and VICA root certificates for you to download from Visa Developer dashboard (Go to Outbound Certificates section under Project Credentials).
  5. Visa will notify you (via email) of the client 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. You can download all 3 certificates from the Visa Developer dashboard, and create a certificate chain (.pem file). For details, refer to Certificate Chaining Steps.
    2. Once the certificate is chained and you have the .pem file, add it to your trust-store (required for Mutual-SSL 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. Whitelist 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 whitelist 103.144.116.26. For Mumbai whitelist 198.217.248.24.
    Note: In an Outbound call, Visa acts as a client and you cannot submit a callback configuration for an event that you have already submitted and is in the pending approval state. All VTS clients supporting India cards will need to do the whitelist.
  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. Post the activation is successful, the callback status changes 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 Configuration

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

  1. Login to developer portal and go to Project configuration under Certification or Production section.
  2. Disable the callback using Toggle option, which when exercised will change the state of callback to "De-activation_Pending".
  3. Post de-activation is successful, the configuration state will change to "Inactive".
  4. You may choose to activate the configuration again, as and when required using the Toggle option.

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

Testing Outbound Configuration

As your outbound 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 he 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 Configuration

To edit outbound configuration:

  1.   Login to your Project on Visa Developer dashboard and go to project Configuration section.
  2. Click on Details option for the configuration you want to edit.
  3. 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.
  4. Visa will acknowledge receipt of your edited configuration and will verify the same.
  5. 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.
  6. 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 Configuration

To delete the outbound configuration, contact your Visa representative.

Note: Delete capability is not supported in the Production environment. You can edit the configuration, if required, from the Visa Developer dashboard.

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 domain configuration until your delete request has entered the "Pending" state.

Re-submitting Rejected Outbound Configuration

Visa has the right to reject an outbound 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 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 configure the client outbound certificate chain (public certificate, VICA intermediate and VICA Root) in your server trust-store. All these certificates will be available for your project from the Visa Developer dashboard. Make sure you download the right certificate for the correct environment (Certification or Production). 
    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. Whitelist 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 whitelist 103.144.116.26. For Mumbai whitelist 198.217.248.24. Note: In an Outbound call, Visa acts as a client and you cannot submit a callback configuration for an event that you have already submitted and is in the pending approval state. All VTS clients supporting India cards will need to do the whitelist.

Certificate Chaining Steps

  1. Make sure you have download the outbound certificates for your project from the Visa Developer dashboard.
  2. Open a text editor (notepad/wordpad) and paste the entire body of each certificate into one text file in the following order:

The Primary Certificate - <<projectName>>_client_certificate.crt

The Intermediate Certificate - VICAIntermediateCA.crt

The Root Certificate - VICATrustedRoot.crt

Make sure to include the beginning and end tags on each certificate. The result should look as shown  below:

-----BEGIN CERTIFICATE-----
<<Your client certificate: client_outbound_certificate.cert>>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<<Your Intermediate certificate: VICAIntermediateCA.cert>>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<<Your Root certificate: VICATrustedRoot.cert>>
-----END CERTIFICATE-----

Save the above file as your_project_domain_name.pem. You can now configure the certificate chain (.pem file) in trust store of your server.