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).
Adding Outbound Configuration
To setup an outbound callback:
- Login to your Visa Developer account.
- Click on Project and go to Configuration section on your dashboard.
- Click on Add Outbound Configuration. This displays a configuration entry dialog box.
- Enter details for domain, path (URL), for example, domain: https://testproject.herokuapp.com. Note: The protocol must be HTTPS.
- Select the Product and Callback from the dropdown and click Submit. A new callback configuration will be created in the product section.
- The callback configuration will be in “Pending” state until it is approved by Visa.
- 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.
- The setup requires configurations, which you need to perform as stated below:
- 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.
- Add this certificate chain in the trust store of your application hosted server. Note: Make sure your server certificate is issued via a certifying authority (CA) on the Visa trusted CA list. (Refer to Certificate Requirements section). Your server domain should be publicly available.
- Whitelist the Visa Outbound public IP: 188.8.131.52 at your end so that Visa notification requests are not blocked. 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.
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.
- Configure your application hosted server by adding the Visa issued client certificate chain into the trust store. This certificate chain is provided by Visa in the Outbound Certificates section under Credentials tab of your project on Visa Developer. You can download the chain using the Download Certificate option. This certificate chain is a bundled certificate, containing client certificate, VICA Intermediate and VICA Root certificates.
- For trusting your server side certificate, it should be issued by a known and Visa trusted Certificate Authority (CA). Self-signed certificates are not accepted. For a detailed list of trusted certifying authorities, click here.
Testing Outbound Configuration
Visa Developer allows you to test your outbound configuration and verify that the URL is reachable by sending a test payload.
- Click Ping Test , which will display the test modal.
- 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
- Your project promotion request form (for certification or production) will have your outbound APIs also promoted to higher environment.
- 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.
- Post submission Visa will review your promotion request.
- 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.
- You will receive acknowledgement mail for your submitted outbound configurations and Visa will verify those for approval.
- 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.
- Login to your Visa Developer account.
- Click on the Project and go to Configuration section on your project (certification or production to which your project is promoted).
- Click on Add Outbound Configuration. This displays a configuration submission modal.
- 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.
- A new outbound configuration will be added for the API and you will get an acknowledgement mail.
- 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:
- Visa will review your submitted configuration, and once reviewed the configuration may be approved.
- 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.
- Once the client certificate is provisioned, the configuration status will change to "Approved" and the configuration state will be “Inactive”.
- 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).
- 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.
- 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.
- Once the certificate is chained and you have the .pem file, add it to your trust-store (required for Mutual-SSL handshake).
- Next, make sure you have whitelisted public IPs for Visa: 184.108.40.206 & 220.127.116.11.
- 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".
- Post the activation is successful, the callback status changes to "Active" and you will be notified (via email) of configuration completion and activation.
- 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.
- Login to developer portal and go to Project configuration under Certification or Production section.
- Disable the callback using Toggle option, which when exercised will change the state of callback to "De-activation_Pending".
- Post de-activation is successful, the configuration state will change to "Inactive".
- 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.
- Click on Ping Test option for the callback and a modal will be displayed listing the Product, Outbound API and API end-point.
- 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.
- Click on Send Test and you will receive a payload on your hosted end-point.
- 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:
- Login to your Project on Visa Developer dashboard and go to project Configuration section.
- Click on Details option for the configuration you want to edit.
- 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. Note: Your existing (old) configuration URL will remain “Active” and you will continue to receive outbound calls on it, until the new one is approved.
- Visa will acknowledge receipt of your edited configuration and will verify the same.
- 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.
- 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:
- Your server certificate needs to be provisioned by one of the Visa trusted CA (Certifying Authority) only. For a detailed list of Visa trusted certifying authorities, click here.
- You need to whitelist Visa public IP(s): 18.104.22.168 & 22.214.171.124
- 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)
Certificate Chaining Steps
- Make sure you have download the outbound certificates for your project from the Visa Developer dashboard.
- 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:
<<Your client certificate: client_outbound_certificate.cert>>
<<Your Intermediate certificate: VICAIntermediateCA.cert>>
<<Your Root certificate: VICATrustedRoot.cert>>
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.