Authorize Method

Description

The Authorize method attempts a funds reservation against the provided card details.

Action

http://www.ecentricswitch.co.za/paymentgateway/v1/Authorize

Style

Document

Input (Literal)

The input of this method is the document element AuthorizeRequest having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
AuthorizeRequest Required
MerchantID Required	string	50	A unique identifier to identify the merchant. Also known as Merchant GUID.
TransactionID Required	string	50	A unique identifier provided by the merchant on the API call to identify the transaction
PreviousTransactionID	string	50	A unique identifier to identify a preceding transaction (Secure3DLookup).
TransactionDateTime	datetime		The transaction timestamp.
SaleReconID	string	100	A unique identifier for reconciliation purposes.
ReconID	string	50	A unique identifier for reconciliation purposes.
Amount Required	long		The authorization amount in the lowest monetary unit.
CurrencyCode	string	3	The currency code according to the ISO 4217 standard. The default for South Africa is ZAR
BudgetPeriod	string	99	Allows a customer to select their chosen budget period.
OrderNumber	string	50	The transaction order or reference number. Note: Only Alphanumeric characters i.e. [a..z], [A..Z], [0..9] are allowed. NO spaces or special characters are allowed. The first 12 characters of this field will be sent to the acquirer/bank as the Retrieval Reference Number (RRN). Therefore the first 12 characters must be unique. Duplicate RRN’s may cause transaction failures.
AuthCode	string	50	The authorization code received from the payment service.
PaymentService Required	PaymentServiceType		The target payment service.
Card	BankCard		The card details.
BankAccount	BankAccountType		The card bank account type.
FirstName	string	50	The customer first name.
LastName	string	50	The customer last name.
BillingAddress	Address		The billing address.
ShippingAddress	Address		The shipping address.
MerchantAddress	Address		The address of the merchant.
Email	string	254	The customer email.
MobilePhone	string	20	The customer mobile phone number.
HomePhone	string	20	The customer home phone number.
WorkPhone	string	20	The customer work phone number.
MerchantPhone	string	16	The phone number of the merchant.
MerchantCustomerServicePhone	string	16	The customer service phone number of the merchant.
PAResPayload	string		The PARes Payload obtained through the 3D Secure authentication process.
TerminalID	string	8	The TerminalID of the merchant. If left blank, the configured value will be used.
CardAcceptorName	string	40	The CardAcceptorName is the merchant name which will appear on the customer's bank statement. If left blank, the configured value will be used. Payment Facilitators are required by the banks to use this CardAcceptorName format
TrialSubscription	nullable boolean		This parameter is optional. It is used when a merchant is offering Trial Subscriptions. The value would be "true" or "false"
MerchantCategoryCode	string	4	This parameter is optional. It is used when a merchant wishes to pass a unique MCC (MerchantCategoryCode) eg: 5399
CardOnFileScenario	CardOnFileScenario	10	An identifier allowing a merchant to indicate which specific CIT (customer initiated) or MIT (merchant initiated) transaction is being performed
VerificationAction	VerificationActionType		The VerificationAction to be applied to the card. If left blank when the PaymentService is CardVerification, it will default to NonPaymentAuthentication. The amount used will be R0 (Zero Rand)
MerchantURL	string	255	This is the website address of the sub merchant. Applicable to aggregators. Max length is 255 characters
SubMerchantID	string	15	This is the unique ID of the Sub Merchant. Only applicable to aggregators. Max length is 15 characters
Secure3DData	Secure3DData		For aggregators or merchants who obtain external Secure3D authentication data.
DigitalWalletPayload	string		This is the encrypted payload from the digital wallet provider. Base64-encoded digital wallet payload

Output (Literal)

The output of this method is the document element AuthorizeResponse having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader Required
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
AuthorizeResponse Required
TransactionID Required	string	50	A unique identifier to identify the transaction.
TransactionDateTime Required	datetime		The transaction timestamp.
ReconID Required	string	50	A unique identifier for reconciliation purposes.
AuthCode	string	50	The authorization code received from the payment service.
TransactionStatus Required	TransactionStatusType		The transaction status (Success or Failure). A merchant must not attempt a Capture if the TransactionStatus = "Failure" in the AuthorizeResponse message
ResponseDetail Required	ResponseDetail		The transaction result code.
AuthAmount	long		The amount authorized by the bank.

Sample Message

Request

Body

<soapenv:Envelope xmlns:soapenv=""http://schemas.xmlsoap.org/soap/envelope/"" xmlns:=""http://www.ecentricswitch.co.za/paymentgateway/v1"">
   <soapenv:Header>
      <MessageHeader>
      </MessageHeader>
   </soapenv:Header>
   <soapenv:Body>
      <AuthorizeRequest>
        <MerchantID>8B67BF88-BB8D-4EB5-ADFC-0F5C97C7ED67</MerchantID>
        <TransactionID>9ee8b2be-4d86-494c-8e5f-b2182ce49d71</TransactionID>
       <PreviousTransactionID>0f750d6e-5336-4da1-9cd5-1896797f5f54</PreviousTransactionID>
        <Amount>50</Amount>
        <CurrencyCode>ZAR</CurrencyCode>
        <OrderNumber>MR64503998</OrderNumber>
         <Card>
          <Token>BF392BCE-6DE4-4134-85D1-EA02F7EB633C</Token>
          <SecurityCode>360</SecurityCode>
        </Card>
     <PaymentService>CardNotPresent</PaymentService>
<PAResPayload>cres: ewogICJhY3NUcmFuc0lEIiA6ICI2ZmJiOWMwOS1iMGIyLTRhZDUtODNjMy01MmQ4MjA3NTQ0NDMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjIuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI4MzA0NWVlNi1jMDQ2LTU5MDktODAwMC0wMDAwMDg0MGY2NjciLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ</PAResPayload>
      </AuthorizeRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response

Body

<s:Envelope
	xmlns:s=""http://schemas.xmlsoap.org/soap/envelope/"">
	<s:Header>
		<h:MessageHeader
			xmlns:h=""http://www.ecentricswitch.co.za/paymentgateway/v1""
			xmlns=""http://www.ecentricswitch.co.za/paymentgateway/v1""
			xmlns:xsd=""http://www.w3.org/2001/XMLSchema""
			xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"">
			<MessageDateTime>2024-11-14T12:14:55.953</MessageDateTime>
			<MessageID>6EE64154-FFF6-464A-AD73-794EDF20B879</MessageID>
			<Channel xsi:nil=""true""/>
		</h:MessageHeader>
	</s:Header>
	<s:Body
		xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
		xmlns:xsd=""http://www.w3.org/2001/XMLSchema"">
		<AuthorizeResponse xmlns=""http://www.ecentricswitch.co.za/paymentgateway/v1"">
			<TransactionID>9ee8b2be-4d86-494c-8e5f-b2182ce49d71</TransactionID>
			<TransactionDateTime>2024-11-14T12:14:54.527</TransactionDateTime>
			<SaleReconID xsi:nil=""true""/>
			<ReconID/>
			<AuthCode>868536</AuthCode>
			<TransactionStatus>Success</TransactionStatus>
			<ResponseDetail>
				<Source>Acquirer</Source>
				<Code>00</Code>
				<Description>Approved or completed successfully</Description>
				<ClientMessage>Approved.</ClientMessage>
			</ResponseDetail>
			<AuthAmount>50</AuthAmount>
		</AuthorizeResponse>
	</s:Body>
</s:Envelope>