Documentation Powered by ReDoc

payfy.me API ( 1.0.143 )

Download OpenAPI specification : Download

Support : [email protected] License: Apache 2.0

Payment API

Authentication

bearerAuthentication

The client sends HTTP requests with the Authorization header that contains the word Bearer followed by a space and the Shop Api Key.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Payment

Merchant Payments API

getPayments

Get a list of payments sorted by creation date (most recent first)

Authorizations:
bearerAuthentication
query Parameters
offset
integer [ 0 .. 1000000 ]

The number of items to skip before starting to collect the result set. Default is 0.
limit
integer [ 1 .. 1000 ]

The numbers of items to return. Default is 50.
created.gte
string < ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS) >
Example: created.gte=2021-10-13T10:26:18

If passed, return only payments created at or after the specified time
created.lt
string < ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS) >
Example: created.lt=2021-10-13T10:39:34

If passed, return only payments created strictly before the specified time

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00" ,
  • "status": 200 ,
  • "hasMore": true ,
  • "result": [
    ]
}

createPayment

Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS

Authorizations:
bearerAuthentication
Request Body schema: application/json

Payment Request - Request to initiate a payment

referenceId
string <= 256 characters

Reference assigned by Merchant. Will not go outside the system. Will be sent unchanged in the PaymentResponse.
paymentType
required
string ( PaymentType )
Enum : "DEPOSIT" "WITHDRAWAL" "REFUND"

Payment Type
paymentMethod
string ( PaymentMethod )
Enum : "BASIC_CARD" "FLEXEPIN" "MACROPAY" "SKRILL" "PAYRETAILERS" "LOCALPAYMENT" "MONNET" "PAYPAL" "NETELLER" "TRUSTPAYMENTS" "PAYMAXIS" "GATE8TRANSACT" "TINK" "B2BINPAY" "CLICK" "MONETIX" "PERFECTMONEY" "VOLT"

Payment Method
amount
number multiple of 1e-18 [ 1e-18 .. 999999.99 ]

Payment amount
currency
required
string < ISO 4217 code for FIAT currencies or cryptocurrency symbol >

Payment currency
parentPaymentId
string <= 32 characters

Initial transaction Id
description
string <= 512 characters

Description of the transaction shown to the Customer. Can be sent outside the system.
object ( Card )

You must be PCI DSS compliant to collect card data on your side. If you are not certified, do not add this field to your request and we will collect the data on our page.
object ( Customer )
object ( BillingAddress )

Customer's billing address
returnUrl
string <= 256 characters

URL to redirect Customer after processing
webhookUrl
string

Url to receive payment status notifications
startRecurring
boolean

Send 'true' if you want this payment to initiate recurring chain. Default is 'false'.
recurringToken
string

To continue recurring chain, send a token from a previously initiated recurring payment.

Responses

Request samples

Content type
application/json
{
  • "referenceId": "payment_id=123;custom_ref=456" ,
  • "paymentType": "DEPOSIT" ,
  • "paymentMethod": "BASIC_CARD" ,
  • "amount": 11.12 ,
  • "currency": "EUR" ,
  • "parentPaymentId": "91d27876e87f4b22b3ecd53924bf973d" ,
  • "description": "Deposit 123 via TEST shop" ,
  • "card": {
    } ,
  • "customer": {
    } ,
  • "billingAddress": {
    } ,
  • "returnUrl": " https://mywebsite.com/{id}/{referenceId}/{state}/{type} " ,
  • "webhookUrl": " https://mywebsite.com/webhooks " ,
  • "startRecurring": true ,
  • "recurringToken": "string"
}

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00" ,
  • "status": 200 ,
  • "result": {
    }
}

findPayment

Payment - Find Payment

Authorizations:
bearerAuthentication
path Parameters
id
required
string /[a-zA-Z0-9]{32}/

Payment Id

Responses

Response samples

Content type
application/json
{
  • "timestamp": "2020-10-07T13:36:32.595+00:00" ,
  • "status": 200 ,
  • "result": {
    }
}

Webhooks

In order to recieve webhooks from our system you need to specify 'Webhook Url' in shop settings or provide 'webhookUrl' parameter in createPayment request. The request parameter takes precedence over the parameter specified in shop settings.

To ensure that webhooks come from our system, you can generate a Signing Key in your shop settings. If the Signing Key is specified, webhooks from our system will include 'Signature' header with Hmac256 hash generated from JSON body and Signing Key.

id
string <= 32 characters

Payment Id
referenceId
string <= 256 characters

referenceId from payment request
paymentType
string ( PaymentType )
Enum : "DEPOSIT" "WITHDRAWAL" "REFUND"

Payment Type
state
string ( PaymentState )
Enum : "CHECKOUT" "PENDING" "CANCELLED" "DECLINED" "COMPLETED"

Payment State
description
string <= 512 characters

Description of the transaction
parentPaymentId
string <= 32 characters

Initial transaction Id from payment request
paymentMethod
string ( PaymentMethod )
Enum : "BASIC_CARD" "FLEXEPIN" "MACROPAY" "SKRILL" "PAYRETAILERS" "LOCALPAYMENT" "MONNET" "PAYPAL" "NETELLER" "TRUSTPAYMENTS" "PAYMAXIS" "GATE8TRANSACT" "TINK" "B2BINPAY" "CLICK" "MONETIX" "PERFECTMONEY" "VOLT"

Payment Method
object ( PaymentMethodDetails )
amount
number multiple of 1e-18 [ 1e-18 .. 999999.99 ]

Amount sent to the payment provider
currency
string < ISO 4217 code for FIAT currencies or cryptocurrency symbol >

Currency sent to the payment provider
customerAmount
number

Amount from payment request. Filled only if the request currency differs from the currency sent to the payment provider.
customerCurrency
string < ISO 4217 code for FIAT currencies or cryptocurrency symbol >

Currency from payment request. Filled only if it differs from the currency sent to the payment provider.
redirectUrl
string <= 256 characters

URL to redirect the customer
errorCode
string

Check 'Error Codes' section for details
externalResultCode
string

Result code from external provider
object ( Customer )
object ( BillingAddress )

Customer's billing address
startRecurring
boolean

Indicates whether this payment has started a recurring chain
recurringToken
string

Token that can be used to continue the recurring chain
terminalName
string

The name of the provider that was used to process this payment
{
  • "id": "91d27876e87f4b22b3ecd53924bf973d" ,
  • "referenceId": "payment-123" ,
  • "paymentType": "DEPOSIT" ,
  • "state": "PENDING" ,
  • "description": "Deposit via TEST shop" ,
  • "parentPaymentId": "91d27876e87f4b22b3ecd53924bf973d" ,
  • "paymentMethod": "BASIC_CARD" ,
  • "paymentMethodDetails": {
    } ,
  • "amount": 11.12 ,
  • "currency": "EUR" ,
  • "customerAmount": 15 ,
  • "customerCurrency": "USD" ,
  • "redirectUrl": " http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7 " ,
  • "errorCode": "1.01" ,
  • "externalResultCode": "03" ,
  • "customer": {
    } ,
  • "billingAddress": {
    } ,
  • "startRecurring": true ,
  • "recurringToken": "string" ,
  • "terminalName": "string"
}

Sandbox

For a successful deposit in the sandbox environment, the amount should be less than 10000000. For test withdrawals and refunds, the limit is 10000.

Test cards

Card Number Result
4000 0000 0000 0002 3D-Secure enrolled, successful authorization
4242 4242 4242 4242 3D-Secure enrolled, declined authorization
4000 0000 0000 0408 Not enrolled for 3D-Secure, successful authorization
4000 0000 0000 0416 Not enrolled for 3D-Secure, declined authorization

Error Codes

Code Description
1.00 Illegal Workflow State
1.01 Not Found
1.02 Communication Problem
1.03 Internal Server Error
1.04 Cancelled by Timeout
1.05 Terminal not Found
1.06 Recurring Token not Found
1.07 Payer Unaccepted
1.08 Invalid Amount
1.09 Invalid Currency
2.00 Cancelled by Customer
3.00 Declined by Acquirer
3.01 Declined by Acquirer: Anti-fraud
3.02 Declined by Acquirer: Request Validation
3.03 Acquirer Malfunction
3.04 Acquirer Timeout
3.05 Acquirer Limits Reached
3.06 Declined by Acquirer: Card Scheme
3.07 Declined by Acquirer: Card Data
3.08 Declined by Acquirer: Business Rules
3.09 Not Fully 3DS
3.10 Unknown Error Code
3.11 Payer cannot pay
4.00 Declined by Issuer
4.01 Insufficient Funds
5.00 Declined by 3DS
5.01 3DS Timeout
6.00 Declined by Anti-fraud
6.01 Card PAN Blacklisted
6.02 Customer Email Blacklisted