Payment Post-Authorization Enrichment

POST https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment

Endpoint Overview

Purpose

Enrich pre-auth payment transaction events that were sent to the Fraud Score Endpoint with additional post-auth information.

Applicability

Suitable for those using a pre-auth integration.

• Events to Send: Post-auth authorizations (auth) and post-auth auth_captures.
• Note: Enables the addition of post-auth fields (eci, cavvresult, avsresult, cvvresult, and responsecode) to pre-auth transactions. This endpoint does not return a fraud score.

Request Parameters

Request parameters in JSON format

{
  "customer": "customer-placeholder",
  "transactionid": "00000001",
  "transactiontype": "auth",
  "avsresult": "A",
  "cvvresult": "S",
  "eci": "02",
  "responsecode": "05",
  "success": "true",
  "timestamp": 1646063615,
  "authresult": "success",
  "cavvresult": "5",
  "ddresult": "ZXC* Site Access 800-123-4567",
  "gatewaydeclinereason": "Card Disabled",
  "ucafindicator": "2"
}

Request parameters: Field Reference Table

Field	Data Type	Payment Fraud (Issuer)	Payment Fraud (Acquirer / Processor)	Merchant Fraud / AML	Description
transactionid	String	Critical & Required	Critical & Required	Critical & Required	The unique identifier of the transaction event. Every transaction event, so auth, capture, auth_capture, etc., has its own unique ID.
timestamp	Double	Critical & Required	Critical & Required	Critical & Required	The UTC time at which the transaction was made. When sending events in realtime, this will usually be 'now'. Only Unix Timestamps are accepted.
transactiontype	String	Critical & Required	Critical & Required	Critical & Required	The type of transaction event. Accepted values are: - auth: An authorization is used to reserve funds on the customer's card without yet deducting them. - capture: A capture is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card. A capture should always be linked to at least one authorization via the parenttransactionid. - auth_capture: A simultaneous combination of auth and capture in the same transaction, for when there is no need to perform these operations separately. - refund: A refund transaction returns credit to a customer's payment method. - void: A void transaction is the explicit discarding of authorization of funds. - top_up: Increases the available credit of a credit card. - incremental_auth: A transaction that increases the authorised amount of a confirmed auth transaction that has not yet been captured. - reversal: A reversal cancels the transaction and re-credits the customer's payment method. This happens directly after the transaction has taken place but before the funds have been fully processed. - none: Use only when the transactiontype is unknown.
customer	String	Critical & Required	Critical & Required	Critical & Required	The name of Fraudio's client that makes the API call.
success	String	Critical & Required	Critical & Required	Critical & Required	This indicates the overall result of the transaction. Accepted values are: - true: Transaction fully completed without any failures (both technical and non-technical). - false: Any part of the transaction failed or did not meet the necessary criteria, regardless of technical success. - none: The outcome of the transaction is uncertain or not yet known. Please use true only for fully successful transactions. Use false if there's any doubt or known issues, and none when outcome information is incomplete.
responsecode	String	Critical & Required	Critical & Required	Critical & Required	The response code is a numerical code that indicates the outcome of authorization checks of issuing banks. The code must be a 2 character ISO8583-1987 response.
avsresult	String	Important	Important	Important	AVS (Address Verification System) result is the outcome of a check performed for Card-not-Present and MOTO transactions on the billing address provided by the shopper to see if the provided address matches the address on file with the card issuer. Accepted values are: - A: Addresses match/ZIP codes do not. - B: Street addresses match, but ZIP codes not verified due to incompatible formats. - C: Street address and postal/ZIP codes not verified due to incompatible formats. - D: Street addresses and postal/ZIP codes match (VISA). Customer name incorrect, ZIP codes match (AMEX / JCB). - E: Customer name incorrect, billing address and ZIP code match. - F: Street addresses and postal codes match (VISA). Customer name incorrect, billing address matches (AMEX / JCB). - G: Address information not verified for international transaction. - I: Address information not verified. - K: Customer name matches. - L: Customer name and ZIP code match. - M: Street addresses and postal/ZIP codes match. - N: No match. - O: Customer name and billing address match. - P: Postal/ZIP codes match. Acquirer sent both postal/ZIP code and street address, but street address not verified due to incompatible formats. - R: Retry: System unavailable or timed out. Issuer ordinarily performs address verification but was unavailable. - S: AVS not supported. - T: Nine-digit zip code matches, address does not match. - U: Information is unavailable. - W: For U.S. Addresses, nine-digit postal code matches, address does not. For address outside the U.S. postal code matches, address does not (MasterCard / Discover). Customer name, billing address, and postal code are all correct ( AMEX / JCB). - X: For U.S. addresses, nine-digit postal code and addresses matches. For addresses outside the U.S., postal code and address match. - Y: Street address and postal/ZIP match. - Z: Postal/ZIP match, street addresses do not match or street address not included in request. - none: Unknown.
authresult	String	Supplementary	Supplementary	Supplementary	Indicates if the transaction successfully passed all authentication and authorization checks. Accepted values are: - fail: failed authentication and authorization. - success: successful authentication and authorization. - none: Unknown.
cavvresult	String	Important	Important	Important	The Cardholder Authentication Verification Value (CAVV) is a value that allows VISA to validate the integrity of the Verified by Visa (VbV) transaction data for VISA 3Ds transactions. Accepted values are: - 0: CAVV authentication results invalid, no verification performed. - 1: CAVV failed verification (authentication), Issuer approves authorization. - 2: CAVV passed verification (authentication), Issuer approves authorization. - 3: CAVV passed verification (attempt), Issuer approves authorization. - 4: CAVV failed verification (attempt), Issuer approves authorization. - 5: Not Used - Reserved. - 6: CAVV not verified (VisaNet flag for Issuer not selected), Issuer approves authorization. - 7: CAVV failed verification (attempt), Issuer approves authorization. - 8: CAVV passed verification (attempt), Issuer approves authorization. - 9: CAVV failed verification (attempt), Issuer approves authorization. - A: CAVV passed verification (attempt), Issuer approves authorization. - B: CAVV passed verification (authentication). - C: CAVV failed verification (attempt). - D: CAVV failed verification (authentication). - none: Unknown.
cvvresult	String	Important	Important	Important	Card Verification Value (CVV) result is the outcome of a check performed on the security code provided by the shopper to see if it matches the code on file with the card issuer. Accepted values: - M: CVV2 Match. - N: CVV2 No Match. - P: Not processed. - S: CVV2 should be on the card. - U: Issuer does not participate in CVV2 service, or participates but has not provided the encryption keys, or both. - X: No response from association. - none: Unknown.
ddresult	String	Supplementary	Supplementary	Supplementary	The dynamic descriptor result returned by the processor is the text that represents businesses on bank account statements. Can be up to 22 characters long.
eci	String	Important	Important	Important	The Electronic Commerce Indicator (ECI) is the value indicating the outcome of 3D-Secure (3DS) authentication attempted on transactions where 3DS is enabled. Different card schemes use different values. Accepted values for Visa / American Express / JCB / Discover / Diners are: - 05: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful. - 06: Either cardholder or card issuing bank is not 3D enrolled. - 07: Authentication is unsuccessful or not attempted. - none: Unknown. Accepted values for MasterCard are: - 02: Both cardholder and card issuing bank are 3D enabled. 3D card authentication is successful. - 01: Either cardholder or card issuing bank is not 3D enrolled. - 00: Authentication is unsuccessful or not attempted. - none: Unknown.
gatewaydeclinereason	String	n.a.	Important	Important	The gateway decline reason is a code provided by the payment gateway indicating the reason for a declined transaction. Declinecodes differ from gateway to gateway, therefore the reason of the decline is preferred. Any declinereason is accepted. E.g. Application Incomplete, Duplicate, Fraud, Risk Thresholds, Card Disabled.
merchantadvicecode	String	Supplementary	Supplementary	Supplementary	The merchant advice code is a code provided by the merchant's payment processor that indicates the reason for a declined transaction, and how it can be retried.
ucafindicator	String	Supplementary	Supplementary	Supplementary	The Universal Cardholder Authentication (UCAF) indicator indicates to what extend the UCAF data collection is supported for MasterCard 3DS transactions. Accepted values are: - 0: UCAF data collection is not supported by the merchant. - 1: UCAF data collection is supported by the merchant, and UCAF data may be present and contain an attempted AAV. - 2: UCAF data collection is supported by the merchant and UCAF data must be present and contain a fully authenticated AAV. - none: Unknown.

Response Parameters

Status Code	Status Message	Description	Schema
200	OK	Standard response for successful HTTP requests.	200 OK - Payment Post-Authorization Enrichment Response
4xx, 500, 501, 502, 503, 504	error	Various error messages for unsuccessful HTTP requests.	Problem response

Code samples

Shell

curl -X POST 'https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment' \
  -H "authorisation: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}'

Python

import json
import os

import requests

payment_post_authorization_enrichment_endpoint = 'https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment'
access_token = os.environ['ACCESS_TOKEN']
headers = {'Content-Type': 'application/json','authorisation': f'Bearer {access_token}'}
post_auth_data = {"customer": "customer-placeholder", "transactionid":"00000001","transactiontype":"capture","avsresult":"A","cvvresult":"S","eci":"02","responsecode":"05","success":"true","timestamp":1646063615,"authresult":"success","cavvresult":"5","ddresult":"ZXC* Site Access 800-123-4567","gatewaydeclinereason":"Card Disabled","ucafindicator":"2"}
r = requests.post(payment_post_authorization_enrichment_endpoint, data=json.dumps(post_auth_data), headers=headers)
print(r.json())

Java

package com.fraudio;

import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PaymentPostAuthorizationEnrichment
{
    public static void main(String[] args)  throws IOException, URISyntaxException, InterruptedException
    {
        String paymentPostAuthorizationEnrichmentEndpoint = "https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment";
        String accessToken = System.getenv("ACCESS_TOKEN");
        String postAuthData = "{\"customer\": \"customer-placeholder\",\"transactionid\":\"00000001\",\"transactiontype\":\"capture\",\"avsresult\":\"A\",\"cvvresult\":\"S\",\"eci\":\"02\",\"responsecode\":\"05\",\"success\":\"true\",\"timestamp\":1512828988826,\"authresult\":\"success\",\"cavvresult\":\"5\",\"ddresult\":\"ZXC*SiteAccess800-123-4567\",\"gatewaydeclinereason\":\"CardDisabled\",\"ucafindicator\":\"2\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(new URI(paymentPostAuthorizationEnrichmentEndpoint))
            .header("authorisation", String.format("Bearer %s", accessToken))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(postAuthData))
            .build();
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        String responseBody = response.body();
        System.out.println("Response Code: " + response.statusCode() + " Response Body: " + responseBody);
    }
}

Perl

use LWP::UserAgent;
use HTTP::Request::Common;

my $payment_post_authorization_enrichment_endpoint = 'https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment';
my $access_token = $ENV{"ACCESS_TOKEN"};
my $post_auth_data = '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}';
my $req = HTTP::Request -> new(POST => $payment_post_authorization_enrichment_endpoint);
$req -> header('authorisation' => "Bearer $access_token", "Content-Type" => "application/json");
$req -> content($post_auth_data);
my $ua = LWP::UserAgent -> new;
my $resp = $ua -> request($req);
my $message = $resp -> decoded_content;
print "Received reply: $message";

PHP

<?php
  $payment_post_authorization_enrichment_endpoint = 'https://api.fraudio.com/v1/transactions/payment-post-authorization-enrichment';
  $access_token = $_SERVER["ACCESS_TOKEN"];
  $post_auth_data = '{"customer": "customer-placeholder","transactionid": "00000001","transactiontype": "capture","avsresult": "A","cvvresult": "S","eci": "02","responsecode": "05","success": "true","timestamp": 1646063615,"authresult": "success","cavvresult": "5","ddresult": "ZXC* Site Access 800-123-4567","gatewaydeclinereason": "Card Disabled","ucafindicator": "2"}';
  $options = [
    'http' => [
        'header'  => "authorisation: Bearer $access_token" .
                     "Content-Type: application/json",
        'method'  => 'POST',
        'content' => $post_auth_data
    ]
  ];
  $context  = stream_context_create($options);
  $result = file_get_contents($payment_post_authorization_enrichment_endpoint, false, $context);
  print $result;
?>