# Parse IPN Messages

When webhooks are triggered in the gateway, a notification is sent as a POST request to the specified destination URL. The post body contains two x-www-form-urlencoded parameters:

pg_signature
pg_payload

This payload is signed to ensure that the message originated from OPAC gateway and was not modified in transit. The message is identical to standard API responses and contains a snapshot of the related entity at the time the IPN was triggered.

# Exceptions

An invalid signature exception is raised if the IPN you attempt to parse has an invalid signature.

# Handling notifications

function notification_handler(){

	$pgSignature = $_POST["pg_signature"];
    $pgPayload = $_POST["pg_payload"];

    // Return to home page if empty payload or signature
    if (empty($pgPayload) || empty($pgSignature)) {
        wp_redirect(get_home_url());
        exit();
    }	

    $header = array_change_key_case(apache_request_headers(),CASE_LOWER);
    $header_authorization = $header['authorization'];
    
    // Check if authorization header is equal to the IPN private key
    if(!empty($this->ipn_pkey)){
        if($header_authorization !== $this->ipn_pkey){
            return http_response_code(401);
        }
    }

    $this->get_opac_api();	
    $notification = OPAC_Notification::parse($pgSignature, $pgPayload);		

    $response = false;

    if($notification->resource_type == OPAC_Notification::TYPE_PAYMENT){

        if($notification->kind == OPAC_Notification::KIND_PAYMENT_CAPTURE_COMPLETED)
        {
            $response = $this->notification_payment_captured($notification);
        }
        else if($notification->kind == OPAC_Notification::KIND_PAYMENT_CAPTURE_DENIED)
        {
            $response = $this->notification_payment_capture_denied($notification);		
        }
        else if($notification->kind == OPAC_Notification::KIND_PAYMENT_AUTHORIZATION_VOIDED)
        {
            $response = $this->notification_payment_authorization_voided($notification);
        }
        else if($notification->kind == OPAC_Notification::KIND_PAYMENT_REFUND_COMPLETED)
        {
            $response = $this->notification_payment_refunded($notification);
        }
        else if($notification->kind == OPAC_Notification::KIND_PAYMENT_REFUND_DENIED)
        {
            $response = $this->notification_payment_refund_denied($notification);
        }
        else{
            $response = true;
        }
    }
    else{
        $response = true;
    }


    $http_code = $response ? 200 : 400;

    return http_response_code($http_code);
}

# Notification Message structure

# id string

Identifier of the Notification Message Sent
# create_time datetime

Notification Message creation time as defined in RFC 3339 Section 5.6.
# resource_type string

Notification resource type. Valid values are payment, subscription, account_updater
# kind string

Event kind that triggered the notification
- # PAYMENT.AUTHORIZATION.CREATED
  
  Authorization is created successfully
- # PAYMENT.AUTHORIZATION.DENIED
  
  Authorization is declined for some reason
- # PAYMENT.SALE.COMPLETED
  
  Sale (authorisation and capture) successfully created.
- # PAYMENT.AUTHORIZATION.VOIDED
  
  Authorization successfully cancelled
- # PAYMENT.AUTHORIZATION.VOID.DENIED
  
  Authorization void declined for some reason
- # PAYMENT.CAPTURE.COMPLETED
  
  Payment transaction captured successfully
- # PAYMENT.CAPTURE.DENIED
  
  Payment transaction capture declined for some reason
- # PAYMENT.CAPTURE.DEFERRED
  
  Payment transaction capture deferred
- # PAYMENT.REFUND.COMPLETED
  
  Payment transaction refunded successfully
- # PAYMENT.REFUND.DENIED
  
  Payment transaction refund declined for some reason
- # PAYMENT.REFUND.DEFERRED
  
  Payment transaction refund deferred
# resource object

payload associated with the notification event message. This payload will highly depend on the notification kind.

# Payment Notification Resource

If notification resource type is payment, the resource object structure is defined below :

# id string

Identifier of the payment resource created.
# reference_id string

In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced.
# state string

The state of the payment, authorization, or order transaction. The value is:
- Authorised. The transaction was successfully authorised.
- Pending. The transaction is currently pending.
- Captured. The transaction has been captured.
- Refunded. The transaction has been refunded.
- Declined. The transaction has been declined.
- Expired. The transaction has been expired.
- Cancelled. The transaction has been cancelled.
- Voided. The transaction has been voided.
- Timeout. The transaction has been timeout.
- Deferred Refund. The transaction refund has been deferred.
- Flagged. The transaction has been flagged.
- Deferred Capture. The transaction Capture has been deferred.
- Card Verified. The card has been verified.
# invoice_number string

invoice number to track this payment (Maximum length: 50.)
# payer_id string

Encrypted Payer ID.
# credit_card_id string

ID of the credit card being saved for later use.
# amount object

Amount being collected.
# create_time datetime

Payment creation time as defined in RFC 3339 Section 5.6.

# result

# code string

Code identifying the result on our system
# message string

Message related to the code
# description string

Long description of the code identifying the result on our system
# authorisation_code string

Authorisation code:

When the payment is authorised successfully, this field holds the authorisation code for the payment. When the payment is not authorised, this field is empty.

Example: 58747
# cascaded string

Indicates whether the transaction has cascaded to another acquirer
# risk_check string

Indicate whether risk checks was enabled and performed
# redirect_url string

When the payment flow requires a redirect, this contains information about the redirect URL.
# actions ArrayOf(action)

List of actions performed by the payment transaction and its corresponding results.

# action

# code string

Code identifying the result on our system
# message string

Message related to the code
# description string

Long description of the code identifying the result on our system
# action string

The name of the action performed by the payment transaction to obtain the corresponding result
# id string

Identifier of the payment resource created corresponding to the action performed.
# state string

State of the payment action performed. The value is:
- Authorised. The transaction was successfully authorised.
- Pending. The transaction is currently pending.
- Captured. The transaction has been captured.
- Refunded. The transaction has been refunded.
- Declined. The transaction has been declined.
- Expired. The transaction has been expired.
- Cancelled. The transaction has been cancelled.
- Voided. The transaction has been voided.
- Timeout. The transaction has been timeout.
- Deferred Refund. The transaction refund has been deferred.
- Flagged. The transaction has been flagged.
- Deferred Capture. The transaction Capture has been deferred.
- Card Verified. The card has been verified.

# amount

# currency string

The three-character ISO-4217 currency code.
# total string

The total amount charged to the payee by the payer. Maximum length is 10 characters, which includes:
- Seven digits before the decimal point.
- The decimal point.
- Two digits after the decimal point.

← Delete a card associated to a payer Common Object Definitions →

# Parse IPN Messages

# Exceptions

# Handling notifications

# Notification Message structure

# id string

# create_time datetime

# resource_type string

# kind string

# PAYMENT.AUTHORIZATION.CREATED

# PAYMENT.AUTHORIZATION.DENIED

# PAYMENT.SALE.COMPLETED

# PAYMENT.AUTHORIZATION.VOIDED

# PAYMENT.AUTHORIZATION.VOID.DENIED

# PAYMENT.CAPTURE.COMPLETED

# PAYMENT.CAPTURE.DENIED

# PAYMENT.CAPTURE.DEFERRED

# PAYMENT.REFUND.COMPLETED

# PAYMENT.REFUND.DENIED

# PAYMENT.REFUND.DEFERRED

# resource object

# Payment Notification Resource

# id string

# reference_id string

# state string

# invoice_number string

# payer_id string

# credit_card_id string

# amount object

# create_time datetime

# result

# code string

# message string

# description string

# authorisation_code string

# cascaded string

# risk_check string

# redirect_url string

# actions ArrayOf(action)

# action

# code string

# message string

# description string

# action string

# id string

# state string

# amount

# currency string

# total string

# id `string`

# create_time `datetime`

# resource_type `string`

# kind `string`

# resource `object`

# id `string`

# reference_id `string`

# state `string`

# invoice_number `string`

# payer_id `string`

# credit_card_id `string`

# amount `object`

# create_time `datetime`

# code `string`

# message `string`

# description `string`

# authorisation_code `string`

# cascaded `string`

# risk_check `string`

# redirect_url `string`

# actions `ArrayOf(action)`

# code `string`

# message `string`

# description `string`

# action `string`

# id `string`

# state `string`

# currency `string`

# total `string`