Global Payments API
GP Developer PortalGP API reference
HomeAPI ReferenceSDKsContext Plugin
Authentications

Initiate

POST
/authentications/{id}/initiate

For 3DS 2, submit data including the billing and shipping details of the payer, at least one phone number, the device data, transaction details, outcome from the ACS Method URL if it took place and a link to the merchant's About or Contact page. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.

The Challenge_Return_Notification callback is sent to the URL supplied in an earlier request ({$request.body#/notifications/challenge_return_url}); see POST /authentications.

Authorization

bearerAuth
AuthorizationBearer <token>

Access token from POST /accesstoken, sent as Authorization: Bearer <token>.

In: header

Path Parameters

id*string

A unique identifier that is used to identify and reference an instance of this resource. It is generated by Global Payments to identify the authentication and must be used to action or reference that authentication.

Length1 <= length <= 50

Header Parameters

X-GP-Idempotency?string

Integrator generated value submitted in the request header that is checked to ensure the same value has not been seen in the last 24 hours. It is used to ensure idempotency is maintained with this action.

Length1 <= length <= 50
X-GP-Version*string

The version of the API to execute the request.

Length1 <= length <= 50
Default"2021-03-22"

Request Body

application/json

three_ds*
merchant_contact_url*string

The url of the website that shows the merchant's contact details. Please note that local URLs are not allowed. The URL provided has to be valid

payment_method*
order*
browser_data*
method_url_completion_status?string

Indicates whether the 3DS Method was completed successfully.

  • YES
  • NO
Length1 <= length <= 50

Value in

  • "YES"
  • "NO"
message_category?string

Indicates the reason category the authentication was initiated.

  • PAYMENT_AUTHENTICATION - The authentication relates to a payment.
  • NON_PAYMENT_AUTHENTICATION - non payment activity such as adding or maintaining cards or card verification (OTB).
Length1 <= length <= 50

Value in

  • "PAYMENT_AUTHENTICATION"
  • "NON_PAYMENT_AUTHENTICATION"
stored_credential?
payer?
payer_login_data?
payer_prior_three_ds_authentication_data?
recurring_authorization_data?

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/authentications/AUT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d/initiate" \  -H "X-GP-Version: 2021-03-22" \  -H "Content-Type: application/json" \  -d '{    "method_url_completion_status": "YES",    "three_ds": {      "source": "BROWSER"    },    "merchant_contact_url": "https://enp4qhvjseljg.x.pipedream.net/",    "order": {      "time_created_reference": "2019-04-26T10:19:32.552327Z",      "amount": "5089",      "currency": "EUR",      "reference": "3400dd37-101d-4940-be15-3c963b6109b3",      "address_match_indicator": "TRUE",      "shipping_address": {        "line1": "Apartment 852",        "line2": "Complex 741",        "line3": "House 963",        "city": "Chicago",        "postal_code": "50001",        "state": "IL",        "country": "840"      },      "gift_card_count": 1,      "gift_card_currency": "EUR",      "gift_card_amount": "25000",      "delivery_email": "james.mason@example.com",      "delivery_timeframe": "ELECTRONIC_DELIVERY",      "shipping_method": "ANOTHER_VERIFIED_ADDRESS",      "shipping_name_matches_cardholder_name": "YES",      "preorder_indicator": "MERCHANDISE_AVAILABLE",      "preorder_availability_date": "2019-04-18",      "reorder_indicator": "FIRST_TIME_ORDER",      "category": "GOODS_SERVICE_PURCHASE"    },    "payment_method": {      "card": {        "number": "4012001038488884",        "expiry_month": "12",        "expiry_year": "30"      }    },    "payer": {      "reference": "6dcb24f5-74a0-4da3-98da-4f0aa0e88db3",      "account_age": "LESS_THAN_THIRTY_DAYS",      "account_creation_date": "2019-01-10",      "account_change_date": "2019-01-28",      "account_change_indicator": "THIS_TRANSACTION",      "account_password_change_date": "2019-01-15",      "account_password_change_indicator": "LESS_THAN_THIRTY_DAYS",      "mobile_phone": {        "country_code": "44",        "subscriber_number": "987654321"      },      "home_phone": {        "country_code": "44",        "subscriber_number": "123456789"      },      "work_phone": {        "country_code": "44",        "subscriber_number": "1801555888"      },      "payment_account_creation_date": "2019-01-01",      "payment_account_age_indicator": "LESS_THAN_THIRTY_DAYS",      "suspicious_account_activity": "NO_SUSPICIOUS_ACTIVITY",      "purchases_last_6months_count": 3,      "transactions_last_24hours_count": 1,      "transaction_last_year_count": 5,      "provision_attempt_last_24hours_count": "01",      "shipping_address_time_created_reference": "2019-01-28",      "shipping_address_creation_indicator": "THIS_TRANSACTION"    },    "payer_prior_three_ds_authentication_data": {      "authentication_method": "FRICTIONLESS_AUTHENTICATION",      "acs_transaction_reference": "26c3f619-39a4-4040-bf1f-6fd433e6d615",      "authentication_timestamp": "2020-07-28T10:26:49.712Z",      "authentication_data": "secret123"    },    "recurring_authorization_data": {      "max_number_of_instalments": "05",      "frequency": "25",      "expiry_date": "2019-08-25"    },    "payer_login_data": {      "authentication_data": "secret123",      "authentication_timestamp": "2020-07-28T10:26:49.712Z",      "authentication_type": "MERCHANT_SYSTEM_AUTHENTICATION"    },    "browser_data": {      "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",      "color_depth": "TWENTY_FOUR_BITS",      "ip": "123.123.123.123",      "java_enabled": "TRUE",      "javascript_enabled": "TRUE",      "language": "en-US",      "screen_height": "1080",      "screen_width": "1920",      "challenge_window_size": "FULL_SCREEN",      "timezone": "0",      "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML,like Gecko) Chrome/70.0.3538.110 Safari/537.36"    }  }'
{  "id": "AUT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",  "time_created": "2021-05-03T21:23:39.718Z",  "time_last_updated": "2021-05-03T21:23:39.718Z",  "transaction_type": "SALE",  "status": "AVAILABLE",  "channel": "CP",  "amount": "11099",  "currency": "USD",  "country": "US",  "source": "BROWSER",  "three_ds": {    "server_trans_ref": "string",    "acs_trans_ref": "string",    "acs_reference_number": "string",    "ds_trans_ref": "strin",    "eci": "strin",    "liability_shift": "YES",    "status": "AUTHENTICATION_SUCCESSFUL",    "status_reason": "HIGH_CONFIDENCE",    "authentication_source": "BROWSER",    "message_version": "string",    "authentication_value": "string",    "cardholder_response_info": "string",    "message_category": "PAYMENT_AUTHENTICATION",    "redirect_url": "string",    "acs_challenge_request_url": "string",    "challenge_status": "MANDATED",    "challenge_model": "STATIC_CHALLENGE",    "session_data_field_name": "threeDSSessionData",    "message_type": "CREQ",    "challenge_value": "string",    "exemption_optimization_result": "APPLY_EXEMPTION",    "mobile_data": {      "acs_signed_content": "eyJhbGciOiJQUzI1NiIsIng1YyI6Ik1JSURlVENDQW1HZ0F3SUJBZ0lRYlM0QzRCU",      "acs_rendering_type": "string",      "acs_interface": "NATIVE",      "acs_ui_template": "MULTI_SELECT"    }  },  "notifications": {    "challenge_return_url": "string"  },  "action": {    "id": "ACT_uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",    "type": "CHECK_AVAILABILITY",    "time_created": "2021-05-03T21:23:39.718Z",    "result_code": "SUCCESS",    "app_id": "uzFr7t4VOqxdLDI44hHmXIjHtOOE8d",    "app_name": "my_lovely_app"  }}

Check Availability POST

Start the authentication process by confirming the available mechanisms to authenticate the payer based on a payment method. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.

Obtain Result GET

Obtain the authentication information that must be submitted when creating a transaction to achieve the fraud liability shift from the merchant. Availability of this feature in production depends on your allowed live configuration. Please contact Global Payments before coding this feature to confirm it will be available to you when you go live.