@papara/papara v1.0.4

Table of Contents

Intro

Enums

Account

Banking

Cash Deposit

Mass Payment

Recurring Mass Payment

Payments

Validation

Response Types

Intro

Integrating Papara into your software requires following;

1. Obtain your API Key. So Papara can authenticate integration’s API requests. To obtain your API Key, follow https://merchant.test.papara.com/ URL. After sucessfully logged in, API Key can be viewed on https://merchant.test.papara.com/APIInfo

2. Install client library. So your integration can interact with the Papara API. Install operations are like following.

Configuration

Sample usage:

const client = new PaparaClient("YOUR_API_KEY");
const result = await client.accountService.getAccount();

Installation

# Install via npm
npm install --save @papara/papara

or

# Or install via yarn
yarn add @papara/papara

Enums

CashDepositProvisionStatus

When a cash deposit request was made, following statuses will return and display the status of provision.

Currency

All currencies on the API are listed below.

EntryType

Entry types are used in ledgers and cash deposits in order to track the money in the operation. Possible entry types are listed below.

PaymentMethod

Three types of payment is accepted in the system. Possible payment methods are listed below.

PaymentStatus

After a payment was done, API returns the payment status which are shown below.

Account

This part contains the technical integration information prepared for the use of the account and balance information of the merchant. Account and balance information on Papara account can be retrieved by Account service. Developers can also retrieve the balance history, which contains a list of transactions that contributed to the balance.

Get Account Information

Returns the merchant account and balance information. Balance information contains current balance, available funds and unavailable funds, whilst account information contains brand name and full title of the merchant. To perform this operation use getAccount method on Account service.

Account Model

Account contains account information that returns from API.

AllowedPaymentType

AllowedPaymentType displays allowed payment types.

AccountBalance

AccountBalance shows current balance figures and lists three types of balances and general currency.

Service Method

Purpose

Return account information and current balance for authorized merchant.

Usage

function getAccount() {
    const result = await client.accountService.getAccount();
    return result;
}

List Ledgers

Returns the merchant account history (list of transactions) in paged format. This method is used for listing all transactions made for a merchant including resulting balance for each transaction. To perform this operation use listLedgers method on Account service. startDate and endDate should be provided.

AccountLedger

AccountLedger represents a transaction itself that returns from API.

CurrencyInfo

CurrencyInfo represents the currency information available in a ledger that returns from API.

LedgerListOptions Model

LedgerListOptions is used by account service for providing request parameters for ledger listing operation.

Service Method

Purpose

Returns list of ledgers for authorized merchant.

Usage

function listLedgers() {
	const result = await client.accountService.listLedgers({
    	startDate: new Date(2020, 1, 1).toISOString(),
    	endDate: new Date().toISOString(),
   		page: 1,
   	 	pageSize: 20
  	});
    return result;
}

Get Settlement

Calculates the count and volume of transactions within the given time period. To perform this operation use GetSettlement method on Account service. startDate and endDate should be provided.

Settlement Model

Settlement is used by account service to match returning settlement values API.

SettlementGetOptions Model

SettlementGetOptions is used by account service for providing settlement request parameters.

Service Method

Purpose

Returns settlement for authorized merchant.

Usage

function listLedgers() {
	const result = await client.accountService.getSettlement({
    	startDate: new Date(2020, 1, 1).toISOString(),
    	endDate: new Date().toISOString()
 	});
	return result;
}

Banking

This part contains technical integration information prepared for merchants those who want to quickly and securely list their bank accounts with Papara and/or create a withdrawal request to their bank accounts.

Get Bank Accounts

Retrieves registered bank accounts of the merchant. To perform this operation use getBankAccounts method on Banking service.

BankAccount Model

BankAccount contains bank account information.

Service Method

Purpose

Returns bank accounts for authorized merchant.

Usage

function getBankAccounts() {
    var result = await client.bankingService.getBankAccounts();
    return result;
}

Withdrawal

Generates withdrawal requests for merchants. To perform this operation use withdrawal method on Banking service.

BankingWithdrawalOptions

BankingWithdrawalOptions is used by banking service for providing request parameters.

Service Method

Purpose

Creates a withdrawal request from given bank account for authorized merchant.

Usage

function withdrawal() {
	var bankAccountResult = await client.bankingService.getBankAccounts();

	if (bankAccountResult.data.length > 0) {
    var bankAccount = bankAccountResult.data[0];

    var result = await client.bankingService.withdrawal({
      amount: 10,
      bankAccountId: bankAccount.bankAccountId
    });
  }
    return result;
}

Possible Errors and Error Codes

Cash Deposit

With the integration of Papara physical point, you can become a money loading point and earn money from which end users can load balance to their Papara accounts. Physical point integration methods should only be used in scenarios where users load cash to Papara accounts.

Get Cash Deposit Information

Returns cash deposit information. To perform this operation use getCashDeposit method on Cash Deposit service. id should be provided.

CashDeposit Model

CashDeposit is used by cash deposit service to match returning cash deposit values from API

CashDepositGetOptions

CashDepositGetOptions is used by cash deposit service for providing request parameters

Service Method

Purpose

Returns a cash deposit information

Usage

function getCashDeposit() {
    const result = await client.cashDepositService.getCashDeposit({
    	id: 123456789 // cash deposit ID
 	 });
    return result;
}

Create Cash Deposit With Phone Number

It deposits money to the user from the physical point. using user’s phone number. To perform this operation use createWithPhoneNumber method on Cash Deposit service. phoneNumber, amount and merchantReference should be provided.

CashDepositToPhoneOptions

CashDepositToPhoneOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Creates a cash deposit request using end users's phone number.

Usage

function createWithPhoneNumber() {
    const result = await client.cashDepositService.createWithPhoneNumber({
    	phoneNumber: config.PersonalPhoneNumber,
    	amount: 10,
        merchantReference: uuidv4() //random number generator method, place actual merchant reference here
  	});
    return result;
}

Get Cash Deposit By Reference

Returns the information of the money loading process from the physical point with the merchant reference information. To perform this operation use getCashDepositByReference method on Cash Deposit service. reference should be provided.

CashDepositByReferenceOptions

CashDepositByReferenceOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Returns a cash deposit object using merchant's unique reference number.

Usage

function getCashDepositByReference() {
    var result = await client.cashDepositService.getCashDepositByReference({
    	reference: "78cadfb9-71d1-42dd-9793-84e90af53b07"
 	});
    return result;
}

Create Cash Deposit With Account Number

Deposits money to the user with Papara number from the physical point. To perform this operation use createWithAccountNumber on Cash Deposit service. accountNumber, amount and merchantReference should be provided.

CashDepositToAccountNumberOptions

CashDepositToAccountNumberOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Creates a cash deposit request using end user's account number.

Usage

function createWithAccountNumber() {
	const result = await client.cashDepositService.createWithAccountNumber({
    	accountNumber: config.PersonalAccountNumber,
   	 	amount: 10,
    	merchantReference: uuidv4() //random number generator method, place actual merchant reference here
  	});
    return result;
}

Create Cash Deposit With National Identity Number

Deposits money to the user with national identity number registered in Papara from the physical point. To perform this operation use createWithTckn on Cash Deposit service. tckn, amount and merchantReference should be provided.

CashDepositToTcknOptions

CashDepositToTcknOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Creates a cash deposit request using end users's national identity number.

Usage

function createWithTckn() {
	const result = await client.cashDepositService.createWithTckn({
   		tckn: config.TCKN,
   		amount: 10,
   		merchantReference: uuidv4() //random number generator method, place actual merchant reference here
  	});
    return result;
}

Create Cash Deposit Provision With National Identity Number

Creates a request to deposit money from the physical point using national identity number registered in Papara without provision. To perform this operation use createProvisionWithTckn on Cash Deposit service. phoneNumber, tckn, amount and merchantReference should be provided.

CashDepositProvision Model

CashDepositProvision is used by cash deposit service to match returning cash deposit provision values from API.

CashDepositTcknControlOptions

CashDepositTcknControlOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Creates a cash deposit request without upfront payment using end user's national identity number.

Usage

function createProvisionWithTckn() {
    const result = await client.cashDepositService.createProvisionWithTckn({
        amount: 10,
        merchantReference: uuidv4(), //random number generator method, place actual merchant reference here
        phoneNumber: config.PersonalPhoneNumber,
        tckn: config.TCKN
    });
    return result;
}

Create Cash Deposit Provision With Phone Number

Creates a request to deposit money from the physical point using phone number registered in Papara without provision. To perform this operation use createProvisionWithPhoneNumber on Cash Deposit service. phoneNumber, amount and merchantReference should be provided.

Service Method

Purpose

Creates a cash deposit request without upfront payment using end users's phone number.

Usage

function createProvisionWithPhoneNumber() {
  	const result = await client.cashDepositService.createProvisionWithPhoneNumber({
    	amount: 10,
        merchantReference: uuidv4(), //random number generator method, place actual merchant reference here
        phoneNumber: config.PersonalPhoneNumber
    });
    return result;
}

Create Cash Deposit Provision With Account Number

Creates a request to deposit money from the physical point using Papara number without provision. To perform this operation use createProvisionWithAccountNumber on Cash Deposit service. accountNumber, amount and merchantReference should be provided.

Service Method

Purpose

Creates a cash deposit request without upfront payment using end users's phone number.

Usage

function createProvisionWithAccountNumber() {
  	const result = await client.cashDepositService.createProvisionWithAccountNumber({
		amount: 10,
        merchantReference: uuidv4(), //random number generator method, place actual merchant reference here
        accountNumber: config.PersonalAccountNumber
    });
    return result;
}

Cash Deposit Approval

With the reference code created by the user, it checks the request for deposit without a prepayment from the physical point and makes it ready for approval. To perform this operation, use createProvisionByReferenceControl on Cash Deposit service. referenceCode and amount should be provided.

CashDepositControlOptions

CashDepositControlOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Makes a cash deposit ready to be completed.

Usage

function createProvisionByReferenceControl() {
  	const result = await client.cashDepositService.createProvisionWithAccountNumber({
		amount: 10,
        merchantReference: uuidv4(), //random number generator method, place actual merchant reference here
        accountNumber: config.PersonalAccountNumber
    });
    return result;
}

Cash Deposit Completion

Confirms the deposit request created from the physical point to the user without prepayment. To perform this operation, use completeProvision on Cash Deposit service. id and transactionDate should be provided.

CashDepositCompleteOptions

CashDepositCompleteOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Completes a cash deposit request without upfront payment.

Usage

function completeProvision() {
    // create provision
	const result = await client.cashDepositService.createProvisionWithAccountNumber({
		amount: 10,
      	merchantReference: uuidv4(), //random number generator method, place actual merchant reference here
     	accountNumber: config.PersonalAccountNumber
    });
    
  // complete provision
    var completionResult = await client.cashDepositService.completeProvision({
        id: result.data.id,
        transactionDate: result.data.createdAt
    });
    return result;
}

Get Cash Deposit By Date

Retrieves information of money deposits from the physical point. To perform this operation, use getCashDepositByDate on Cash Deposit service. startDate, endDate, pageIndex and pageItemCount should be provided.

CashDepositByDateOptions

CashDepositByDateOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Returns a cash deposit information by given date.

Usage

function getCashDepositByDate() {
    var result = await client.cashDepositService.getCashDepositByDate({
        startDate: new Date(2020, 1, 1).toISOString(),
        endDate: new Date().toISOString(),
        pageIndex: 1,
		pageItemCount: 20
    });
    return result;
}

Settlements

Returns the total number and volume of transactions performed within the given dates. Both start and end dates are included in the calculation. To perform this operation, use provisionSettlements on Cash Deposit service. startDate and endDate should be provided.

CashDepositSettlementOptions

CashDepositSettlementOptions is used by cash deposit service for providing request parameters.

Service Method

Purpose

Returns total transaction volume and count between given dates. Start and end dates are included.

Usage

function provisionSettlements() {
    var result = await client.cashDepositService.provisionSettlements({
    	startDate: new Date(2020, 1, 1).toISOString(),
   		endDate: new Date().toISOString()
    });
    return result;
}

Possible Errors and Error Codes

Mass Payment

This part is the technical integration statement prepared for merchants those want to distribute payments to their users quickly, safely and widely through Papara.

Get Mass Payment

Returns information about the payment distribution process. To perform this operation use getMassPayment method on MassPayment service. id should be provided.

Mass Payment Model

MassPayment is used by mass payment service to match returning mass payment values from API.

MassPaymentGetOptions

MassPaymentGetOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Returns mass payment information for authorized merchant.

Usage

function getMassPayment() {
    var result = await client.massPaymentService.getMassPayment({
   		id: 123456789
  	});
    return result;
}

Create Mass Payment To Account Number

Send money to Papara number. To perform this operation use createMassPaymentWithAccountNumber method on MassPayment service. accountNumber, amount and massPaymentId should be provided.

MassPaymentToPaparaNumberOptions

MassPaymentToPaparaNumberOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a mass payment to given account number for authorized merchant.

Usage

function createMassPaymentWithAccountNumber() {
    var result = await client.massPaymentService.createMassPaymentWithAccountNumber({
      	accountNumber: config.PersonalAccountNumber.toString(),
      	amount: 1,
      	description: "Unit Test nodejs: MassPaymentToPaparaNumber",
      	massPaymentId: uuidv4(),//random number generator method, place actual mass payment id here
     	parseAccountNumber: 1,
		turkishNationalId: config.TCKN
    });
    return result;
}

Create Mass Payment To E-Mail Address

Send money to e-mail address registered in Papara. To perform this operation use createMassPaymentWithEmail method on MassPayment service. email, amount and massPaymentId should be provided.

MassPaymentToEmailOptions

MassPaymentToEmailOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a mass payment to given e-mail address for authorized merchant.

Usage

function createMassPaymentWithEmail() {
    var result = await client.massPaymentService.createMassPaymentWithEmail({
    	amount: 1,
    	description: "Unit Test nodejs: MassPaymentToEmail",
    	massPaymentId: uuidv4(), //random number generator method, place actual mass payment id here
    	email: config.PersonalEmail,
    	turkishNationalId: config.TCKN
  	});
    return result;
}

Create Mass Payment To Phone Number

Send money to phone number registered in Papara. To perform this operation use createMassPaymentWithPhoneNumber method on MassPayment service. phoneNumber, amount and massPaymentId should be provided.

MassPaymentToPhoneNumberOptions

MassPaymentToPhoneNumberOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a mass payment to given phone number for authorized merchant.

Usage

function createMassPaymentWithPhoneNumber() {
    var result = await client.massPaymentService.createMassPaymentWithPhoneNumber({
      	amount: 1,
      	description: "Unit Test nodejs: MassPaymentToPhoneNumber",
      	massPaymentId: uuidv4(), //random number generator method, place actual mass payment id here
      	phoneNumber: config.PersonalPhoneNumber,
		turkishNationalId: config.TCKN
    });
    return result;
}

Possible Errors and Error Codes

Recurring Mass Payment

This section is the technical integration document prepared for the merchants who want to distribute payments to their users in a fast, secure and widespread through Papara.

Recurring Mass Payment Model

RecurringMassPayment class is used by recurring mass payment service to match returning recurring mass payment values from API.

Create Recurring Mass Payment To Account Number

To perform this operation use CreateRecurringMassPaymentWithAccountNumber method on MassPayment service. AccountNumber, Amount, ExecutionDay, Description and Period should be provided.

RecurringMassPaymentToAccountNumberOptions

RecurringMassPaymentToAccountNumberOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a recurring mass payment to given account number for authorized merchant.

Usage

function createRecurringMassPaymentWithAccountNumber() {
    var result = await client.massPaymentService.createRecurringMassPaymentWithAccountNumber({
      	accountNumber: config.PersonalAccountNumber.toString(),
      	amount: 1,
        turkishNationalId: config.TCKN, //optional
        currency:1, //optional
        period:1,
        description: "Unit Test nodejs: RecurringMassPaymentToPaparaNumber",
        executionDay:1
    });
    return result;
}

Create Recurring Mass Payment To Email

To perform this operation use CreateRecurringMassPaymentWithEmail method on MassPayment service. Email, Amount, TurkishNationalId, Period, Currency, ExecutionDay and Description should be provided.

RecurringMassPaymentToEmailOptions

RecurringMassPaymentToEmailOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a recurring mass payment to given email address for authorized merchant.

Usage

function createRecurringMassPaymentWithEmail () {
    var result = await client.massPaymentService.createRecurringMassPaymentWithEmail ({
      	email: config.PersonalEmail,
      	amount: 1,
        turkishNationalId: config.TCKN, //optional
        currency:1, //optional
        period:1,
        description: "Unit Test nodejs: RecurringMassPaymentToEmail",
        executionDay:1
    });
    return result;
}

Create Recurring Mass Payment To Phone Number

To perform this operation use CreateRecurringMassPaymentWithPhoneNumber method on MassPayment service. PhoneNumber, Amount, TurkishNationalId, Period, Currency, ExecutionDay and Description should be provided.

RecurringMassPaymentToPhoneNumberOptions

RecurringMassPaymentToPhoneNumberOptions is used by mass payment service for providing request parameters.

Service Method

Purpose

Creates a recurring mass payment to given phone number for authorized merchant.

Usage

function createRecurringMassPaymentWithPhoneNumber  () {
    var result = await client.massPaymentService.createRecurringMassPaymentWithPhoneNumber  ({
      	phoneNumber: config.PersonalPhoneNumber,
      	amount: 1,
        turkishNationalId: config.TCKN, //optional
        currency:1, //optional
        period:1,
        executionDay:1,
        description: "Unit Test nodejs: RecurringMassPaymentToPhoneNumber"
        
    });
    return result;
}

Possible Errors and Error Codes

Payments

Payment service will be used for getting, creating or listing payments and refunding. Before showing the payment button to users, the merchant must create a payment transaction on Papara. Payment records are time dependent. Transaction records that are not completed and paid by the end user are deleted from Papara system after 1 hour. Completed payment records are never deleted and can always be queried with the API.

Get Payment

Returns payment information. To perform this operation use getPayment method on Payment service. id should be provided.

Payment Model

Payment is used by payment service to match returning payment values from API.