Skip to main content

Authorize Transaction

To Authorize a charge, use this route and create a transaction.

POSTv1/authorize

Request Body Params​

AttributeTypeDescription
net_valueint32Amount to be charged without the acquisition fees. Must be passed in cents.
gross_amoutint32Final amount to be charged with fees. Must be passed in cents.
installmentsstringNumber of installments of the transaction, being minimum: 1 and maximum: 12.
order_idstringTransaction ID on WU platform.
payment_methodstringPayment method. Accepted values: credit and debit.
wu_payment_typestringSpecific Western Union Payment Type. Accepted values: MT (Money Transfer) and FX(Stars). Default MT
card_holder_namestringCard Holder Name.
card_numberstringCard Number.
card_expiration_datestringCard Expiration Date, with YYYY-MM format.
card_cvvstringCard Verification Code.
customer_namestringCustomer name.
customer_document_numberstringCustomer document number.
customer_emailstringCustomer email.
customer_phone_numberstringCustomer's phone number.
customer_address_zipcodestringCEP (domestic customers - in Brazil) or ZIP (foreign customers) of the customer.

Max length: 9 characters.
customer_address_countrystringCustomer's nationality, in country acronym format. Only the ISO 3166-1 alpha-2 (two-letter) format will be accepted E.g.: BR, US, CA...

Max length: 2 characters.
customer_address_statestringState of the current customer address, in State acronym format, ISO 3166-1 alpha-2 (two-letter). E.g.: TX, WY, MO...

Max length: 2 characters.
customer_address_citystringCity of the customer's address.

Max length: 50 characters.
customer_address_neighborhoodstringNeighborhood of the customer's address.

Max length: 45 characters.
customer_address_streetstringStreet of the customer's address.

Max length: 54 characters.
customer_address_numberstringCustomer's address number.

Max length: 5 characters.
customer_address_complementstringOptional parameter of the complement of the customer's address.

Max length: 14 characters.
soft_descriptorstringDescription that will appear on your customer's invoice. Maximum of 13 characters, being alphanumeric and spaces.
capturebooleanOptional parameter indicating whether or not transaction data should be captured immediately. Accepted values: true and false. Default false.

3DS​

An Authorization can be performed with or without 3DS Authentication. To proceed with an Authorization WITH 3DS, it will be necessary to pass all the extra parameters described below, in the body of the request.

AttributeTypeDescription
authentication_valuestringThe authentication cryptogram must be sent in this field.
authentication_resultstringIndicates the authentication result. Accepted values: CRPT, DENY, AUTH and UCRP.
authentication_transaction_idstringThe transaction ID generated by the 3D Secure authentication server.
authentication_transaction_status_indicatorstringIndicates verification/authentication status. Accepted values: Y, N, A and I.
authentication_status_reasonstringCardinal StatusReason Value.

Authentication Result​

Below is a brief explanation of the authentication_result parameter.

ValueDescription
CRPTIndicates successful authentication and the cryptogram will be sent.
DENYIndicates the transaction was not authenticated.
AUTHIndicates that an authentication attempt was made and the sender does not support the protocol.
UCRPIndicates that authentication was successful and that the cryptogram will not be sent.

Transaction Status Indicator​

Below is a brief explanation of the authentication_transaction_status_indicator parameter.

ValueDescription
YVerification of authentication successful.
NNot authenticated / Account not confirmed.
AIndicates authentication/verification attempts were made. Transaction was not authenticated/verified, but proof of attempt is provided.
IInformational only. Indicates that ACS acknowledges the 3DS requester's preference not to contest the transaction, as the data sent was for informational purposes only.

Cardinal && Marlim​

!

We compared the parameters described above with those of Cardinal to facilitate the integration to the WU, as follows the table below

Marlim AttributeCardinal Attribute
authentication_valueCardinal CAVV.
authentication_transaction_idCardinal DSTransactionId.
authentication_transaction_status_indicatorCardinal PAResStatus.
authentication_status_reasonCardinal StatusReason.

The only parameter that could not be identified was the authentication_result, since it is a conditional tag and must be sent by the WU according to the Authenticator result, following the logic of the values described above: CRPT, DENY, AUTH or UCRP.

info

To proceed with an Authorization WITHOUT 3DS, simply ignore sending the extra parameters described above.

Good to Know

As our Acquirer's integration with WU's 3DS Authentication Provider (Cardinal) has different terminologies and values, there may be some unidentified errors during the Development phase.

We ask the WU team to let us know about these possible errors so that we can adjust both this Documentation and the API so that the values are passed from correctly and the Authorization is carried out successfully.

Response Object​

PropertyTypeDescription
acquirer_status_codestringIssuing Bank response identifier code.
statusstringRepresents the current state of the transaction. Possible values: paid, authorized, and refused.
authorization_codestringAuthorization code returned by the issuing bank.
nsustringCode that identifies the transaction in the acquirer.
order_idstringTransaction ID on WU platform.
date_createddateTimeTransaction creation date in ISODateTime format.
date_updateddateTimeTransaction status updated date in ISODateTime format.
net_valueint32Amount in cents to be charged without acquiring fees.
authorized_amountint32Amount in cents authorized in transaction.
paid_amountint32Amount in cents captured in the transaction.
refunded_amountint32Amount in cents reversed in transaction.
installmentsstringNumber of installments the customer paid for.
transaction_idstringTransaction identifier number.
card_holder_namestringName of cardholder used for payment.
card_brandstringBrand of the card used for the payment. Possible values: visa, mastercard, amex, hypercard and elo.
card_first_digitsstringFirst 6 digits of the card used for payment.
card_last_digitsstringLast 4 digits of the card used for payment.
tip

We create a dedicated page with all possible codes that will be returned in the acquirer_status_code parameter.
Take a look: Authorizer Return Codes.

Samples​

Request
curl -X POST "https://api.wu.global.marlim.co/v1/authorize" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "net_value": 100000,
  "gross_amout": 104330,
  "installments": "1",
  "order_id": "123456789",
  "card_holder_name": "Luke Skywalker",
  "card_number": "5555444433332222",
  "card_expiration_date": "2026-08",
  "card_cvv": "123",
  "customer_name": "Luke Skywalker",
  "customer_document_number": "00099988877",
  "customer_email": "luke@jedimaster.sw",
  "customer_phone_number": "+18007770133",
  "customer_address_zipcode": "95351",
  "customer_address_country": "US",
  "customer_address_state": "CA",
  "customer_address_city": "Modesto",
  "customer_address_neighborhood": "East Modesto",
  "customer_address_street": "Sunset Ave",
  "customer_address_number": "713",
  "soft_descriptor": "Star Wars"
}'
Response200
{
  "acquirer_status_code": "0000",
  "status": "authorized",
  "authorization_code": "068194",
  "nsu": "987654321",
  "order_id": "123456789",
  "date_created": "2024-04-29T17:55:12.745Z",
  "date_updated": "2024-04-29T17:55:12.745Z",
  "net_value": 100000,
  "authorized_amount": 104330,
  "paid_amount": 0,
  "refunded_amount": 0,
  "installments": "1",
  "transaction_id": "12345678912345",
  "card_holder_name": "Luke Skywalker",
  "card_brand": "visa",
  "card_first_digits": "555544",
  "card_last_digits": "2222"
}