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. Only 0-9, A-Z or a-z allowed. Spaces are not allowed
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 sub merchant. Applicable to aggregators.
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 sub merchant. Applicable to aggregators.
PAResPayload	string		The PARes Payload obtained through the 3D Secure authentication process.
TerminalID	string	8	The TerminalID to be passed in Postilion field 41 for Card transactions. If left blank, the configured value will be used.
CardAcceptorName	string	40	The CardAcceptorName to be passed in Postilion field 43 for Card transactions. 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.

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

Bo

<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>