Class: PaysecureApiDocumentationLive::PayinApIsApi

Inherits:
BaseApi
  • Object
show all
Defined in:
lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb

Overview

PayinApIsApi

Constant Summary

Constants inherited from BaseApi

BaseApi::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseApi

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseApi

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from PaysecureApiDocumentationLive::BaseApi

Instance Method Details

#create_purchase(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user
client.city
client.country ISO-3166 Country Code. It must be upper case.
This
should be "CA" for Interac
client.stateCode Example “AL”, “XZ”.. Must be in upper case.
client.street_address
client.zip_code
client.phone
client.full_name
purchase.currency ISO 4217 code for currency you want to send the
transaction in.
This should be 'CAD' for Interac
purchase.products.name
purchase.products.price Price in decimal format.
example 1:


EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

expireInMin

This parameter, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" description here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 288

def create_purchase(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success3.method(:from_hash))
                .is_api_response(true))
    .execute
end

#create_purchase1(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Fields Notes
client.email The customer's email.
client.city The customer's city.
client.country ISO-3166 Country Code. Must be upper case. Example “SG”
(Alpha2)
client.stateCode Example “AL”, “XZ”. Must be in upper case.
Client.street_address The customer's address.
client.zip_code The customer's ZIP or postal code. If country=US, zip
format must be NNNNN or NNNNN-NNNN.
purchase.currency ISO 4217 code for currency you want to send the

transaction in.

Please note, the currency has to be enabled by the account manager for your account. | | purchase.products | An object which contains the list of products which the customer is buying. | | purchase.products.name | The name of the product. | | purchase.products.price | Price in decimal format.
example 1:
EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful. | | pending_redirect | URL to send the user if the transactions is in pending. | | failure_redirect | URL to send the user if the transactions is unsuccessful. |

Optional Parameters

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

Digital Signature (Optional Parameter) :

To ensure authenticity and non-repudiation of the the pay in request, there is an option to digitally sign the pay in request by using the merchant's public key. Public key generation :- Signature generation :- This digitial signature is generated by encrypting the following elements of the pay in request: Plaintext= Client.email+purchase.currency+ purchase.products.price+brand_id Example of encrypt plaintext with public key in java:-

private String encryptData(String plaintext, PublicKey publicKey) throws
Exception {
    Cipher cipher = Cipher.getInstance("RSA");
    cipher.init(Cipher.ENCRYPT_MODE, publicKey);
    byte[] encryptedbytes = cipher.doFinal(message.getBytes());
    return new String(Base64.getEncoder * ().encode(encryptedbytes));
}

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" description here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1699

def create_purchase1(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:deserialize_primitive_types))
                .deserialize_into(proc do |response| response&.to_s end)
                .is_api_response(true)
                .is_primitive_response(true))
    .execute
end

#get_status(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 165

def get_status(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchasesSuccess1.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status1(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 336

def get_status1(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success3.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status2(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase, including its history

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired The purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 615

def get_status2(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success7.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status3(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 773

def get_status3(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchasesSuccess2.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status4(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 942

def get_status4(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success10.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status5(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1313

def get_status5(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchasesSuccess1.method(:from_hash))
                .is_api_response(true))
    .execute
end

#get_status6(purchase_id) ⇒ ApiResponse

This API tells you about all the details of a purchase (PayIn), including its history Note: With respect to bank transfers, the purchase request is synonymous with the PayIn request.

Mandatory

you need to pass the PurchaseID in the API URL

Possible Value of Status

Status Notes
paid Transaction Successful
payment_in_process Payment is under Processing
expired Purchase has Expired.
error Transaction has Failed.

Response Examples

In the response examples you can see instances of both Paid and Error Status purchases.

Error Details

If there are any issues on the Purchase you can get more details from the transaction_data.attempts.error attribute of the response object

Errors

If there are any errors then it'll be in the format of :

{
    "message": "descriptive error message",
    "code": "error_code"
}

Please see the Status Code section for further details. here

Parameters:

  • purchase_id (String) —

    Required parameter: TODO: type description

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1747

def get_status6(purchase_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/api/v1/purchases/{purchaseId}',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .template_param(new_parameter(purchase_id, key: 'purchaseId')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success22.method(:from_hash))
                .is_api_response(true))
    .execute
end

#payin_ap_is(body) ⇒ ApiResponse

1. Request Payload Structure

Supply a JSON payload with these top‐level objects:

  • client (customer details)

  • purchase (order details)

  • paymentMethod (string, must be "SPEI")

  • extraParam (optional, leave {} if unused)

  • status (set to "created")

  • brand_id (your merchant/brand UUID)

  • Redirect & callback URLs

2. Displaying SPEI Instructions to End User

Once you parse payInDetails from the response:

  1. Show CLABE, Beneficiary & Amount

  2. Display Expiration

  3. Show Redirect Path (Optional)

    • If you’re using the hosted checkout_url, simply redirect customers to it and let Paysecure handle the UI.

3. Webhook Handling & Status Transitions

  1. Configure Webhooks

    • In Paysecure’s Dashboard, set your success_callback and failure_callback URLs (one for each event type).

  2. Listen for These Events:

    • payment.paid – Banco de México has settled the transfer.

    • payment.error – CLABE/amount mismatch or network error.

    • payment.expired – Customer did not pay before expireInMin.

  3. Update Order Status:

    • On payment.paid: mark as paid, trigger fulfillment, send confirmation.

    • On payment.error: alert customer, allow retry or alternative payment.

    • On payment.expired: cancel order. here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1014

def payin_ap_is(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success11.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) which can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user
client.city An Identifier for a user
client.country ISO-3166 Country Code. It must be upper case.
This
should be "CA" for Interac
client.stateCode Example “AL”, “XZ”.. Must be in upper case.
client.street_address
client.zip_code
client.phone
client.full_name
purchase.currency ISO 4217 code for currency you want to send the
transaction in.
This should be 'CAD' for Interac
purchase.products.name name of the product or service
purchase.products.price Price in decimal format.
example 1:


EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful | | pending_redirect | URL to send the user if the transactions is in progress | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

expireInMin

The purchase.expireInMin, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 117

def purchases(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchaseSuccess.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases1(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user
client.city An Identifier for a user
client.country ISO-3166 Country Code. It must be upper case.
This
should be "CA" for Interac
client.stateCode Example “AL”, “XZ”.. Must be in upper case.
client.street_address
client.zip_code
client.phone
client.full_name
purchase.currency ISO 4217 code for currency you want to send the
transaction in.
This should be 'CAD' for Interac
purchase.products.name name of the product or service
purchase.products.price Price in decimal format.
example 1:


EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful | | pending_redirect | URL to send the user if the transactions is in progress | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

expireInMin

The purchase.expireInMin, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 461

def purchases1(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchaseSuccess1.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases2(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Request Body Parameters:

Parameter Notes
client.full_name Conditional.
But Recommended to pass the
complete name of the client. Atleast 2 words recommended.
client.email Conditional.
But Recommended to pass a correct email
id.
client.tax_number Mandatory.
Pass the CPF (Brazilian tax
identification number of customer), must contain 11 digits.
paymentMethod Conditional.
Mandatory if you are not using
Paysecure Cashier. Else Non Mandatory.
Value: PIX
purchase.currency Mandatory.
ISO 4217 code for currency you want
to send the transaction in. This should be 'BRL' for PIX.
purchase.products.name Mandatory.
purchase.products.price Mandatory.
Price in decimal format upto 2

decimals.
example 1:
EUR 5 , should be sent as 5.00
example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Mandatory.
Obtain from Dashboard section of your merchant account login. | | success_redirect | Mandatory.
URL to send the user if the transactions is successful. | | pending_redirect | Mandatory.
URL to send the user if the transactions is in progress state. | | failure_redirect | Mandatory
URL to send the user if the transactions has failed. | Note: the object “pix_payload.payload” contains all the necessary fields to create a page containing a QR code and other information on the merchant portal. The field “pix_payload.qr_code” value is in Base64. This can be used to show the QR code image. The field "pix_payload.expiration_date" is in UTC time.

Essential Optional Parameters

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Allowed Limit for this card for particular time period has been consumed

| | | some Mandatory Parameter are missing | | | Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd] | | | Invalid Email Format | | | Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\" parameter | | | Please pass Valid State Code | | | Please pass valid street address in \"street_address\" parameter | | | Please pass valid city name in \"city\" parameter | | | Please pass valid postal Code name in \"zip_code\" parameter | | | You are not Allowed for Live Transaction | | | Merchant Limit is not set | | | Minimum amount is not set for this merchant | | | Brand not found! | | | Your charges setting is incomplete .Plese Contact to Administrator. | | | Only “{curr_name}" currency is allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Invalid_Parameter | You'd usually get it when one or more mandatory parameters are not present in the request. | here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 569

def purchases2(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchaseSuccess2.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases3(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user
client.city
client.country ISO-3166 Country Code. It must be upper case. Example
“SG” (Alpha2)
client.stateCode Example “AL”, “XZ”.. Must be in upper case.
client.street_address
client.zip_code
client.phone
client.full_name
purchase.currency ISO 4217 code for currency you want to send the

transaction in.
Please note, the currency has to be enbaled by the account manager for your account. | | purchase.products.name | | | purchase.products.price | Price in decimal format.
example 1:
EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 725

def purchases3(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchaseSuccess3.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases4(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email The customer's email.
client.city The customer's city.
client.country ISO-3166 Country Code. Must be upper case. Example “SG”
(Alpha2)
client.stateCode Example “AL”, “XZ”. Must be in upper case.
Client.street_address The customer's address.
client.zip_code The customer's ZIP or postal code. If country=US, zip
format must be NNNNN or NNNNN-NNNN.
purchase.currency ISO 4217 code for currency you want to send the

transaction in.

Please note, the currency has to be enabled by the account manager for your account. | | purchase.products | An object which contains the list of products which the customer is buying. | | purchase.products.name | The name of the product. | | purchase.products.price | Price in decimal format.
example 1:
EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful. | | pending_redirect | URL to send the user if the transactions is in pending. | | failure_redirect | URL to send the user if the transactions is unsuccessful. |

Optional Parameters

expireInMin

This parameter, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL. Possible Payment Methods allowed: UPI-QR and UPI-INTENT

Possible Error Messages

| Error Messages | | --- | | Allowed Limit for this payment method for particular time period has been consumed | | some Mandatory Parameter are missing | | Invalid format of Date_of_Birth [allowed format: yyyy-mm-dd] | | Invalid Email Format | | Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\" parameter | | Please pass Valid State Code | | Please pass valid street address in \"street_address\" parameter | | Please pass valid city name in \"city\" parameter | | Please pass valid postal Code name in \"zip_code\" parameter | | You are not Allowed for Live Transaction | | Merchant Limit is not set | | Minimum amount is not set for this merchant | | Brand not found ! | | Your charges setting is incomplete .Plese Contact to Administrator. | | Only {currencyCode} currency is allowed. | | Transaction amount must be equal or greater to minimum trans amount | | Invalid_Parameter
You'd usually get it when one or more mandatory parameters are not present in the request. | here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 894

def purchases4(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:deserialize_primitive_types))
                .deserialize_into(proc do |response| response&.to_s end)
                .is_api_response(true)
                .is_primitive_response(true))
    .execute
end

#purchases5(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user, should be a valid email.
client.city City of the user.
client.country ISO-3166 Country Code. It must be upper case.
client.stateCode ISO-3166-2 State Code. Must be in upper case.
client.street_address street address of the user.
client.zip_code zip code of the user.
client.phone Phone number of the user. Country code is mandatory.

Example: +234999999999
client.full_name Full name of the user. Minimum 2 words with atleast 1
character in each word.
purchase.currency ISO 4217 code for currency you want to send the

transaction in.
eg. This should be 'TZS' for Tanzania
CDF for Congo. | | purchase.products.name | | | purchase.products.price | Amount in decimal upto 2 places. | | brand_id | Obtain from Dashboard section of your merchant account login. | | success_redirect | URL to send the user if the transactions is successful | | pending_redirect | URL to send the user if the transactions is in progress | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

expireInMin

This parameter, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1139

def purchases5(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success13.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases6(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here. The following (see table below) are the mandatory parameters that are required to create a purchase request.

Mandatory parameters in the request body:

Parameter Notes
client.email An Identifier for a user
client.city An Identifier for a user
client.country ISO-3166 Country Code. It must be upper case.
This
should be "CA" for Interac
client.stateCode Example “AL”, “XZ”.. Must be in upper case.
client.street_address
client.zip_code
client.phone
client.full_name
purchase.currency ISO 4217 code for currency you want to send the
transaction in.
This should be 'CAD' for Interac
purchase.products.name name of the product or service
purchase.products.price Price in decimal format.
example 1:


EUR 5 , should be sent as 5.00

example 2:
USD 10 and 37 cents , should be sent as 10.37 | | brand_id | Obtain from Dashboard section of your merchant account login. | | extraParam.IsCryptoPurchase | for paymint, send "Yes" | | success_redirect | URL to send the user if the transactions is successful | | pending_redirect | URL to send the user if the transactions is in progress | | failure_redirect | URL to send the user if the transactions is UNSUCCESSFUL |

Optional Parameters

expireInMin

The purchase.expireInMin, when passed in the PayIn request, sets the time window within which a customer should make the Interac payment through their bank's app. If a customer doesn't complete the payment within the configured time window, the status of the payment will be marked as 'EXPIRED' in Paysecure. However, in certain cases, a payment made outside of this window could still be successful i.e. customer's account may be debited which would result in inconsistencies among Paysecure's, merchant's and customer's status of the transaction. To avoid such cases it is advised to set the expiry time limit appropriately and advise the customers to make payment within this window. However, if there is an inconsistency between the status at Paysecure and at customer's Bank, the merchant and Paysecure will reconcile the amounts during the settlement.

merchantRef

The merchantRef parameter, although not mandatory, is strongly advised for merchants to specify. Its inclusion offers two significant advantages for the merchant:

  1. Prevention of Duplicate Requests: When a merchantRef is utilized, it acts as a unique identifier. This means that if a second purchase request is made using the same merchantRef (reference number), the system will recognize it and prevent duplicate transactions from occurring. This prevents unintended or duplicate purchases.

  2. Facilitation of Transaction Retrieval: In situations where the response from the initial purchase request times out or the 'purchaseId' isn't received, having the merchantRef allows the merchant to retrieve detailed transaction information. This ensures they can track and access the specific purchase details related to that reference, even if the immediate response was not received.

However, if the merchant does not specify the 'merchantRef' parameter, the platform will automatically assign and use an internal 'purchaseId' as a reference for that transaction.

paymentMethod

The paymentMethod parameter identifies which payment solution merchant wants to use to perform a transaction. If parameter is provided, than Paysecure will perform direct payment with the selected payment method instead of loading Paysecure URL.

Possible Error Messages

Error Messages Description
Invalid format of Date_of_Birth[allowed format: yyyy-mm-dd]
Enter Valid Email
Please submit Valid Alpha2 Country Code Ex:(AF,IN) in \"country\"
parameter
Please pass Valid State Code
Please pass valid street address in \"street_address\" parameter
Please pass valid city name in \"city\" parameter
Please pass valid postal Code name in \"zip_code\" parameter
You are not Allowed for Live Transaction
Minimum amount is not set for this merchant
success_redirect/failure_redirect/brand_id is missing
brand_id cannot be null
success_redirect cannot be null
failure_redirect cannot be null
Invalid failure_redirect: minimum 10 characters
purchase.products.price cannot be null
purchase.products[0].name/purchase.products[0].price are missing

| | Your charges setting is incomplete .Plese Contact to Administrator. | | | Currency "curr_name" is Not Allowed | | | Transaction amount must be equal or greater to minimum trans amount | | | Allowed Limit for this card for particular time period has been consumed | | Note: For certain use cases, in addition to long format purchase Id, Paysecure also provides a 7 digit unique code for each purchase starting with digit 4, eg 4000001 “purchaseIdShortCode”: “4000013" here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1265

def purchases6(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PurchaseSuccess.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases7(body) ⇒ ApiResponse

The API endpoint /v1/purchases is a POST request used to create a new purchase. The request body should contain the client information including email, address, and phone, the purchase details such as currency and products, the payment method, and various callback and redirect URLs. Final Steps for Payin APIs Integration

  1. Set Up Authentication & Headers

    • Endpoint: POST >

    • Headers (mandatory):

      - Authorization: Bearer {LIVE_API_KEY}

- Content-Type: application/json

  2. Construct the Request Payload

    • Build a JSON body with:

      - client object (KYC/AML fields):

  - email

  - country (ISO-2 code)

  - city

  - stateCode

  - street_address

  - zip_code

  - phone

- purchase object:

  - currency

  - products array (≥1 item with name and price)

- **Top-level fields:**

  - paymentMethod (e.g., "NEOSURF")

  - brand_id (your Brand UUID)

  - success_redirect (HTTPS URL after success)

  - failure_redirect (HTTPS URL after failure)

  3. Invoke the Payin APIs

  4. Extract Key References

    • purchaseId (e.g., 68394314d3c4ef68d6cbb58c): for tracking/reconciliation.

    • checkout_url (e.g., [https://api.paysecure.net/payments/68394314d3c4ef68d6cbb58c/](https://api .paysecure.net/payments/68394314d3c4ef68d6cbb58c/)): redirect here so the customer can complete voucher entry.

    • Redirect Customer window.location.href = response.checkout_url; Customer enters their 10-digit Neosurf voucher on redirected page.

  5. Listen for Webhook Notifications

    • Ensure your endpoint handles:

      - purchase.paid

- purchase.error

- purchase.cancelled

    • Each payload will include purchaseId, status, amount, currency, etc.

Mandatory Parameters

Field Type Description
Authorization string Bearer {API_KEY} (replace with your live
or staging API key).
Content-Type string Must be application/json.
client.email string Customer’s email (e.g.,
example22@paysecure.net).
client.country string ISO‐3166 Alpha-2 code (e.g., IN).
client.city string City name or code (e.g., 123).
client.stateCode string State or province code (two letters
where possible, e.g., ca).
client.street_address string Street address line (e.g., `test
test`).
client.zip_code string Postal/ZIP code (e.g., 234567).
client.phone string Customer’s phone number (E.164 recommended,
e.g., 9999999999).
purchase.currency string Currency code (e.g., AUD).
purchase.products array Must contain at least one object with
name and price.
└─ products.name string Product name or SKU (e.g., dk).
└─ products.price string Unit price in major currency units
(e.g., "1" = 1.00 AUD).
paymentMethod string Payment rail code (e.g., NEOSURF).
brand_id string Live or staging Brand UUID (e.g.,
c4003b2c-22d4-4dc1-ad0c-c6b54f8c9636).
success_redirect string HTTPS URL to redirect after successful
payment (e.g., https://your.success.redirect.com).
failure_redirect string HTTPS URL to redirect after failed
payment (e.g., https://your.failure.redirect.com).

here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1455

def purchases7(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success16.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases8(body) ⇒ ApiResponse

To Initiate a payment, the very first call to make is /purchases with the required data in the request body. To generate a Purchase, you are required to provide the Brand ID (in the request body) and API key (in the header) Both can be located in the Dashboard section of your merchant account login. The request body structure is shown on the request body of the example request shown here.

💡 Key Fields Explained

Field Description
paymentMethod Always use "CRYPTO-BRIDGE" to trigger this payment
method
currency The fiat currency for the order (e.g., USD, EUR). You will
be paid in crypto but this defines how much the customer will pay
products One or more items being sold, with name and price
extraParam.clientFee Optional: A custom fee you (the merchant) want
to charge — shown to the user at checkout
extraParam.toAddress Optional.
Merchant can provide the list of

wallet addresses, where they want to collect the deposit from the user. Can pass multiple addresses. | | extraParam.toAddress.symbol | The symbol of the digital asset.
Example: ETH, USDC etc.

Possible Values:
AAVE, ADA, APE, APT, ARB, AVAX, BLAST, BLUR, BNB, BTC, BUSD, CAKE, CASH, CRO, DAI, DEXE, DEVNETSOL, DOGE, ENA, ETH, EURC, FARTCOIN, FDUSD, FORM, FTM, GRT, HYPE, IMX, INJ, LDO, LEO, LINK, LTC, MANA, MATIC, MKR, MNT, MON, OP, PAXG, PENGU, POL, PYUSD, QNT, RLUSD, RNDR, S, SAND, SEPOLIAETH, SHIB, SNX, SOL, SUI, TON, TRUMP, TRX, TUSD, UNI, USD1, USD₮0, USDC, USDD, USDG, USDH, USDP, USDT, VIRTUAL, WAVAX, WBNB, WBTC, WETH, WHYPE, WIF, WMATIC, WMON, XLM, XRP | | extraParam.toAddress.networkName | The network of the token.
Example: ETHEREUM, POLYGON etc.

Possible values:
ETHEREUM, POLYGON, BSC, ARBITRUM, OPTIMISM, BASE, AVALANCHEC, BLAST, HYPEREVM, SOLANA, BITCOIN, TRON, LITECOIN, DOGECOIN, RIPPLE, APTOS, CARDANO, STELLAR, SUI, TON, SONIC, INJECTIVE, AVALANCHEX | | extraParam.toAddress.address | The address to send the asset to. | | success_redirect / success_redirect / failure_redirect | Where the user should land after completing or canceling the payment or if the transaction is in pending state. | | success_callback / failure_callback | Your backend URL to receive transaction status via webhook. | | client | Customer billing info | description here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1563

def purchases8(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Purchases1.method(:from_hash))
                .is_api_response(true))
    .execute
end

#purchases9(body) ⇒ ApiResponse

Purchase API Endpoint

This endpoint allows you to create a new purchase transaction. It processes the purchase details, including client information, product details, and payment method, and returns the result of the transaction.

Request Format

  • Method: POST

  • URL: https://api.paysecure.net/api/v1/purchases

  • Request Body: The request should be in JSON format and must include the following structure:

Response Structure

The response will contain the result of the purchase transaction. The structure of the response may include:

  • status: Indicates the success or failure of the transaction.

  • message: A descriptive message regarding the transaction status.

  • transaction_id: Unique identifier for the transaction (if successful).

  • redirect_url: URL to redirect the user based on the transaction result.

Make sure to handle the response appropriately based on the status returned. here

Parameters:

Returns:

  • (ApiResponse) —

    Complete http response with raw body and status code.



1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
 
# File 'lib/paysecure_api_documentation_live/apis/payin_ap_is_api.rb', line 1502

def purchases9(body)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/api/v1/purchases',
                                 Server::SERVER_3)
               .body_param(new_parameter(body)
                            .is_required(true))
               .header_param(new_parameter('application/json; charset=utf-8', key: 'content-type'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Success17.method(:from_hash))
                .is_api_response(true))
    .execute
end