Integrating Payment Systems

Owned by p_demou (Deactivated)
Last updated: Jul 14, 2017
10 min read

Getting Started  

This document provides step by step instructions on how to integrate a Payment system with CRM.COM Payment platform, using a set of Web API methods provided by CRM.COM.

Payments that are automatically generated by the System e.g. in order to automatically pay a bill or Payments that were created using the related Web APIs provided in sections below, can then be processed by CRM.COM's Generic Payment Gateway. For each Payment, a Payment Gateway Request is created which can then be retrieved and processed based on your business' needs. 

Overview

Once the Generic Payment Gateway is set up then all Accounts Receivable should set their Payment Preferences based on the Generic Payment Gateway's configuration settings in order for their related Payments to be processed by the Generic Payment Gateway. 

At the time that a Payment is created and Posted (either manually or through an automatic process of the System), having a payment method related to the Generic Payment Gateway the following steps are followed:

  1. A Payment Gateway Request is created having its life cycle state set to "Pending".
  2. Payment System user can retrieve all Pending Payment Gateway Requests through Web API GET payment_gateway_requests/get_pending.
  3. The Payment Gateway Requests will then be sent to the Generic Payment Gateway through Web API POST payment_gateway_requests/bulk/process.
  4. The Payment Gateway Requests' life cycle state is set to "Under Processing" and the Generic Payment Gateway will respond with the requests that have been successful processed and the requests that haven't be processed due to some error.
  5. The Payment System user can then use either one of the following Web APIs in order to complete the process:

Navigate to Retrieve and Process Payment Gateway Requests section below to find information and examples related to the Web APIs mentioned above.

Check the graphical representation of the flow below

Generic Payment Gateway Flow

Best Practices

Authentication

Before performing any logical unit of work, an authentication token must be acquired. Acquiring an authentication token can be accomplished by using one of the two methods:

  • Web API Keys (preferred option)  
  • Username & Password. 

Visit API Authentication for more information. Also check the Best Practices section below to find out some tips that will help you while Integrating with a POS System.

Using Fields Set

CRM.COM Web API offers the possibility to select the fields to be retrieved from each API method by specifying the fields_set input parameter. This parameter provides the possibility to filter the results and retrieve only the fields that are provided on the method (separated by a comma). If nothing is specified in fields_set then all the fields will be retrieved.  

Visit Using Fields Sets for more information and examples.

Using Pagination

There are API methods which retrieve a large number of entities such as list API methods. Some of these CRM.COM API methods provide the option to apply pagination on the results retrieved. 

Visit Using Pagination for more information and examples.

Integration Flow

Implement Generic Payment Gateway

Payment Gateways are third-party systems used to perform Payments. CRM.COM supports partial handling of Payments for other third-party Payment Gateways, referred to as Generic Gateways.

CRM.COM creates Requests for Payments that are intended for Generic Gateways and which can be further handled by WEB APIs. CRM.COM Web APIs can, for example, be used to collect all Payment Requests that require handling by a Payment Gateway, as well as to update CRM.COM with the results of the Payment Requests, i.e. whether the Requests were completed or rejected.

For more information related to Generic Payment Gateways and how to set them up, visit Generic Gateways.

Submit Payments

A Payment is a financial document issued by a customer to a business to settle an outstanding balance. Payments are crediting the customer's Accounts.

Payments can be created through the CRM.COM System or through related Web APIs. There are three ways to create a Payment either through the System or through Web APIs. Check examples of the Web APIs below.

  1. Manually create the payment through the Web API POST payments/create and have the possibility to allocate it to existing Invoices or Bills of the customer.
    1. The payment_method_identifier will determine if the payment will be processed by the Generic Payment Gateway. 

      Web API example POST payments/create

      POST Request
       http://host_name/crmapi/rest/v2/payments/create
      Body
       {
    "token": "{{token}}",
    "accounts_receivable_identifier":{"number":"100"},
    "type_identifier":{"name":"Payment"},
    "life_cycle_state":"POSTED",
    "payment_method_identifier":{"name":"Generic Payment Gateway"},
    "accounts_receivable_payment_preference_identifier":{"payment_preference_identifier":{"name":"Generic Payment Gateway"}},
    "payment_amount":"50",
	"accounts_receivable_payment_preference_identifier":{"payment_preference_identifier":{"name":"Generic Payment Gateway"}},
	"fields_set":"number,payment_amount,id,payment_gateway_reference_number,posted_on",
}
      Response
       {
  "status": {
    "message": "",
    "description": "",
    "code": "OK"
  },
  "data": {
    "payment_amount": 50,
    "number": "111",
    "id": "123123123123",
	"payment_gateway_reference_number":"111",
    "posted_on": "2017-06-07T13:10:43"
  }
}
  2. Pay an Invoice through the Web API POST payments/pay_invoice
    1. The payment_method_identifier will determine if the payment will be processed by the Generic Payment Gateway. 

      Web API example POST payments/pay_invoice

      POST Request
      http://host_name/crmapi/rest/v2/payments/pay_invoice
      Body
        {
    "token": "{{token}}",
    "accounts_receivable_identifier":{"number":"100"},
    "type_identifier":{"name":"Invoice Payment"},
    "payment_method_identifier":{"name":"Generic Payment Gateway"},    
    "invoice_identifier":{"reference_number":"100"},	
	"accounts_receivable_payment_preference_identifier":{"payment_preference_identifier":{"name":"Generic Payment Gateway"}},
	"fields_set":"number,payment_amount,id,payment_gateway_reference_number,posted_on",   
}
      Response
       {
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
        "payment_amount": 220,        
  		"number": "222",
    	"id": "234234234234",
		"payment_gateway_reference_number":"222",
    	"posted_on": "2017-06-07T13:10:43"
    }
}
  3. Pay a Bill through the Web API POST payments/pay_bill
    1. The payment_method_identifier will determine if the payment will be processed by the Generic Payment Gateway. 

      Web API example POST payments/pay_bill

      POST Request
       http://host_name/crmapi/rest/v2/payments/pay_bill
      Body
        {
    "token": "{{token}}",
    "accounts_receivable_identifier":{"number":"100"},
    "type_identifier":{"name":"Bill Payment"},
    "payment_method_identifier":{"name":"Generic Payment Gateway"},    
    "bill_identifier":{"number":"100"},	
	"accounts_receivable_payment_preference_identifier":{"payment_preference_identifier":{"name":"Generic Payment Gateway"}},
	"fields_set":"number,payment_amount,id,payment_gateway_reference_number,posted_on",   
}
      Response
       {
    "status":
    {
        "message": null,
        "description": null,
        "code": "OK"
    },
    "data":
    {
        "payment_amount": 330,        
  		"number": "333",
    	"id": "345345345345",
		"payment_gateway_reference_number":"333",
    	"posted_on": "2017-06-07T13:10:43"
    }
}

Retrieve and Process Payment Gateway Requests

Payment Gateway Requests are used to log Requests sent to Payment Gateways in order to submit a Payment or Payment Cancellation. 

Once a Payment Gateway Request is created because of the Payment creation then the Payment System can:

  • Retrieve the Pending Payment Gateway Requests through the Web API GET payment_gateway_requests/get_pending 

    Web API example GET payment_gateway_requests/get_pending

    GET Request
     {{server}}/crmapi/rest/v2/payment_gateway_requests/get_pending?token={{token}}&payment_gateway_provider_identifier=name=Generic1&from_date=2017-05-23T06:00:00&fields_set=number,type,error_code,error_description
    Response
     {
    "data": [
        {
            "number": "250",
            "error_description": null,
            "error_code": null,
            "type": "PAYMENT"
        },
        {
            "number": "270",
            "error_description": null,
            "error_code": null,
            "type": "PAYMENT"
        }
    ],
    "status": {
        "code": "OK",
        "description": "",
        "message": ""
    }
}
  • Process the Pending Payment Gateway Requests through the Web API POST payment_gateway_requests/bulk/process. The requests are processed so that they will not be retrieved again for processing. At this point the external system will actually process the requests and then post them or reject them accordingly.

    Web API example POST payment_gateway_requests/bulk/process

    POST Request
     {{server}}/crmapi/rest/v2/payment_gateway_requests/bulk/process
    Body
     {
  "token":"{{token}}",
  "payment_gateway_requests_set":
   [
        {
            "request_unique_identifier":"01",
            "payment_gateway_request_identifier":{"number":"250"},
            "reference_number":"R0001"
        },
        {
            "request_unique_identifier":"02",
            "payment_gateway_request_identifier":{"number":"270"},
            "reference_number":"R0002"
        },
        {
            "request_unique_identifier":"03",
            "payment_gateway_request_identifier":{"number":"290"},
            "reference_number":"R0003"
        }
    ]
}
    Response
     {
  "data": {
    "processed_payment_gateway_requests_set": [
      {
        "number": "250",
        "id": "11111111",
        "request_unique_identifier": "01"
      }
    ],
	"processed_payment_gateway_requests_set": [
      {
        "number": "270",
        "id": "22222222",
        "request_unique_identifier": "02"
      }
    ],
    "unprocessed_payment_gateway_requests_set": [
      {
        "error_description": "Error:Cannot Set Payment Gateway Request Into UNDER_PROCESSING Life Cycle State. Payment Gateway Request Life Cycle State is Not PENDING. - Description:Cannot set Payment Gateway Request into UNDER_PROCESSING life cycle state. Payment Gateway Request life cycle state is not PENDING.",
        "error_code": "CannotSetPaymentGatewayRequestUnderProcessingException",
        "request_unique_identifier": "03"
      }
    ]
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

  • Post the successfully processed Pending or Under Processing Payment Gateway Requests through the Web API POST payment_gateway_requests/bulk/post
    Web API example POST payment_gateway_requests/bulk/post

    POST Request
     {{server}}/crmapi/rest/v2/payment_gateway_requests/bulk/post
    Body
     {
  "token":"{{token}}",
  "payment_gateway_requests_set":
   [
        {
            "request_unique_identifier":"01",
            "payment_gateway_request_identifier":{"number":"250"},
            "reference_number":"R0001"
        },
         {
            "request_unique_identifier":"02",
            "payment_gateway_request_identifier":{"number":"270"},
            "reference_number":"R0002"
        },
        {
            "request_unique_identifier":"03",
            "payment_gateway_request_identifier":{"number":"280"},
            "reference_number":"R0003"
        }
    ]
}
    Response
      {
  "data": {
    "processed_payment_gateway_requests_set": [
      {
        "number": "250",
        "id": "11111111",
        "request_unique_identifier": "01"
      }
    ],
    "unprocessed_payment_gateway_requests_set": [
      {
        "error_description": "Error:Cannot Post Payment Gateway Request. Payment Life Cycle State Should Be: Pending Verification. - Description:Cannot post Payment Gateway Request.",
        "error_code": "CannotPostPaymentGatewayRequestException",
        "request_unique_identifier": "02"
      },
      {
        "error_description": "Error:Cannot Post Payment Gateway Request. Payment Life Cycle State Should Be: Pending Verification. - Description:Cannot post Payment Gateway Request.",
        "error_code": "CannotPostPaymentGatewayRequestException",
        "request_unique_identifier": "03"
      }
    ]
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}
  • Reject the not successfully processed Pending or Under Processing Payment Gateway Requests through the Web API POST payment_gateway_requests/bulk/reject

    Web API example POST payment_gateway_requests/bulk/reject

    POST Request
     {{server}}/crmapi/rest/v2/payment_gateway_requests/bulk/reject
    Body
     {
  "token":"{{token}}",
  "payment_gateway_requests_set":
   [
        {
            "request_unique_identifier":"02",
            "payment_gateway_request_identifier":{"number":"270"},
            "reference_number":"R0002",
			"error_code":"XS001",
            "error_description":"Rejected due to invalid data.",
        },
        {
            "request_unique_identifier":"03",
            "payment_gateway_request_identifier":{"number":"280"},
            "reference_number":"R0003",
			"error_code":"XS001",
            "error_description":"Rejected due to invalid data.",
        }		
    ]
}
    Response
     {
  "data": {
    "processed_payment_gateway_requests_set": [
      {
        "number": "270",
        "id": "111111111111",
        "request_unique_identifier": "02"
      }
    ],
    "unprocessed_payment_gateway_requests_set": [
      {
        "error_description": "Error:Cannot Reject Payment Gateway Request. Payment Gateway Request Life Cycle State Should Be: Pending, Under Processing. - Description:Cannot reject Payment Gateway Request.",
        "error_code": "CannotRejectPaymentGatewayRequestException",
        "request_unique_identifier": "03"
      }
    ]
  },
  "status": {
    "code": "OK",
    "description": "",
    "message": ""
  }
}

 

Additional Documentation

Visit CRM.COM Manuals in order to find more information related to the areas / concepts mentioned in above scenarios.

ModuleDescriptionManuals' Link
PaymentsA Payment is a financial document issued by a customer to a business to settle an outstanding balance. Payments are crediting Accounts ReceivableManaging Financial Transactions - Payments
Generic Payment GatewaysA Payment Gateway is an e-commerce application service provider that authorizes credit card payments for e-businesses. Generic Gateways
Automatic Payment RunsAutomatic Payment Run Definitions are a set of user-defined criteria that are used to identify Bills that should automatically be paid or Wallets that should be automatically topped up via a Payment Gateway. They are also used to create refunds Requests for Payments made through Payment Gateways that were cancelled in CRM.COM after they were completed. Using Automatic Payment Run Definitions
Accounts ReceivablesPayment Preferences are set on Accounts Receivables and are used to define the customer's preferred methods of payment for each account. They hold the information, such as bank account and credit card numbers, which is necessary for third party systems to perform payments.Accounts Receivable