Credit

Credits are payment refunds issued by a merchant to a cardholder after the cardholder paid for a product or service, which is then processed by the merchant. Upon approval of a credit request, the issuer moves funds from the merchant bank (acquirer) account to the customer's account. The standard timeframe for the acquirer to transfer funds from the merchant account is typically 2 to 4 days.

Credit

POST /v1/payments/credits

curl –X POST 'https://api.firstoken.co/v1/payments/credits' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "credit",
        "reference_code": "123456789"
    },
    "card":{
        "number": "4111111111111111"
        "expiration_date": "01/2024"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Credit with permanent token

POST /v1/payments/credits

curl –X POST 'https://api.firstoken.co/v1/payments/credits' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "credit",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "expiration_date": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Credit with temporal token

POST /v1/payments/credits

curl –X POST 'https://api.firstoken.co/v1/payments/credits' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "credit",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}",
        "expiration_date": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

Credit with both tokens

POST /v1/payments/credits

curl –X POST 'https://api.firstoken.co/v1/payments/credits' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR API KEY' \
--data-raw '{
    "transaction_info": {
        "type": "payment",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "expiration_date": "{{ 0beb9110-45d6-4df1-9d61-6b8081cd83b2 : detokenize }}",
        "security_code": "{{ fa5f200d-2c48-41a5-a4c8-b4ec27819868 : transaction }}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": 1000,
            "currency": "COP"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1 Market St",
        "address_2": "Suite 200",
        "city": "san francisco",
        "state": "CA",
        "phone_number": "4158880000",
        "email": "[e-mail]",
        "postal_code": "94105"
    },
    "device_info": {
        "ip_address": "12.7.8.120"
    }
}'

With these endpoint we can get the following response

Example of the JSON response

{
    "status": "success",
    "message": "Credit successful",
    "data": {
        "transaction_info": {
            "type": "credit_response",
            "reference_code": "123456789",
            "transaction_id": "0001709064963668730958",
            "request_id": "7090649650186344904953",
            "status": "Pending",
            "reconciliation_id": "7090649650186344904953",
            "created_at": "2024-02-27T20:16:05Z"
        },
        "order_info": {
            "amount_details": {
                "credit_amount": 1000,
                "currency": "COP"
            }
        }
    }
}

Attributes of the response

status: string The status is a string result that only has two possible values. "Success, “Error” or "Fail".

message: string The message value represents a short description about the status code

data: {object} The value of the data represents a set of JSON objects with the transaction’s details:

• transaction_info: {object} The wrapper object of the transaction’s information. Contains:

  • type: string The type of transaction response.

  • reference_code: string

    A reference code for the transaction.

  • transaction_id: string

    Our transaction identifier of the request. It is used in other requests.

  • request_id: string

    The identifier of the request associated with the transaction.

  • status: string

    The status received of the transaction.

  • reconciliation_id: string

    The response identifier for reconciliation logs.

  • created_at: ISO Date

    The ISO Date of the request.

• order_info: {object} The object for the order information sent it in the body request.

  • amount_details: {object} The total amount details, like credit amount and currency.